Temporary beta invitation access

This feature restricts the beta to invited accounts. It is independent of the mobile isBeta setting, which hides unfinished product surfaces. Issue: mobile #994.

User journey

1. The app checks the backend admission policy before mounting tabs or product screens.
2. An unauthenticated visitor sees the themed invitation entry screen. They cannot dismiss it to browse the app.
3. Entering a valid code opens authentication. Validation alone does not spend the invitation.
4. The visitor creates an email/password account or continues with a configured identity provider, including Apple. Existing accounts may also authenticate.
5. The backend redeems the invitation for the authenticated account. Only successful admission opens the app.
6. Future sessions of that admitted account do not require another invitation. Signing out clears transient invitation state. A returning invited user can sign in from the gate; authentication alone cannot admit an account without beta access.

Passwords remain part of the classic email sign-in flow. Apple users do not need a Snag password. Apple private relay is accepted: the login address does not have to match the admin's distribution address.

Existing accounts at transition

Existing email-linked accounts, including Apple accounts without a Snag password, keep access without a code after migration 0056. The cutoff is the database snapshot at its first execution. Anonymous accounts and accounts marked deleted are excluded; account bans and revoked sessions remain enforced. Apply this one-time transition immediately before beta activation.

The migration changes neither sessions nor collections and spends no invitation. An existing valid session can continue; after reinstall or clearing app data, signing into the same admitted account restores access without another code. Accounts created after the snapshot, anonymous accounts linked to email later, and accounts recreated after deletion still need an invitation. Replaying migrations or disabling/re-enabling beta must not admit these accounts: preserve the beta_admission_rollouts marker permanently through those operations.

Admin workflow

In Invitations bêta, a super administrator enters a recipient email and generates a code. The complete code is displayed once and must be copied for distribution. The admin email is used for distribution tracking and regeneration only; it does not restrict which verified identity can redeem the code.

A code admits one account. Distribute it privately. Regenerating for the same recipient disables that recipient's previous unused invitation. It does not revoke an account that has already been admitted. The code is not spent by a failed login, a rejected email code, or an abandoned Apple dialog. If two people attempt to redeem the same invitation, only one account can succeed. Retrying after successful admission must not spend a second code.

Never include invitation codes, authentication credentials, or full recipient addresses in support logs, issue bodies, screenshots, or source control.

Operational behavior

Admission is stored on the server, not as a global unlocked flag on a phone. This prevents signing out of an invited account and inheriting its access under a different account. The mobile entry screen fails closed if the policy request fails or returns malformed data, and offers retry. A valid existing session is preserved while checking; a network error must not erase credentials or a collection.

The backend enforces admission for private account/collection operations, scans and other protected product routes. Authentication, password recovery, OAuth callbacks, beta admission checks and necessary account lifecycle endpoints remain reachable to finish or recover access. An explicit allowlist retains public catalogue, price-read and image endpoints: the current mobile catalogue transport does not attach account credentials. Their underlying data remains public even though the mobile app does not mount catalogue screens before admission. This feature restricts app entry and private operations; it does not turn catalogue media into private data.

Rollout

1. Review and merge the related backend, mobile, admin-copy and documentation PRs into staging after checks.
2. Deploy the backend API with the gate disabled initially. Confirm the policy endpoint returns required: false and normal authentication still works. Deploy this endpoint before the new mobile build: an older API returning 404 cannot unlock the gate.
3. Back up the database before applying additive migrations 0055_beta_admissions.sql and 0056_existing_beta_accounts.sql, after migrations 0053/0054. Review eligible existing accounts before the first execution of 0056, which defines the admission cutoff. Do not edit already-applied invitation migrations. The ingest worker runs migrations at startup; do not restart it merely to inspect configuration.
4. Deploy the matching admin wording and distribute a mobile build containing the entry gate.
5. Prepare invitations for new accounts. Migration 0055 preserves recorded invitation redemptions; migration 0056 additionally admits existing email/Apple accounts once. Existing testers do not need a new code after this transition.
6. Set BETA_GATE_ENABLED=true in the API runtime environment and recreate the API container through the approved deployment process. All replicas must use the same setting. The default is disabled; changing a host environment file does not update an existing container.
7. Verify with dedicated test accounts: existing email/Apple session remains admitted, new account after the cutoff needs an invitation, rejected code, cancelled Apple flow, successful admission, reuse refused for another account, logout/login, and normal email/password recovery.

Old mobile builds cannot display the new gate and may receive access errors once enforcement is enabled. Coordinate the beta build update before activation. A merge is not a production deployment; record the actual deployed versions separately.

Before enabling, verify the admin paths listed in the backend runbook. Source inspection found invitation generation and account administration use PostgreSQL directly, outside the API guard; their live deployment still needs checking. An operator write token alone does not provide user admission to protected API routes. The runbook also records the endpoint allowlist, deployment environment forwarding and isolated test commands; it becomes available on staging when the backend PR is merged.

Disable after beta

Set BETA_GATE_ENABLED=false in the API runtime environment and recreate the API container through the same approved deployment process. GET /auth/beta/status must then report required: false, including with an expired session token; invitation-required signup and product API admission checks must both stop. No mobile release, account recreation, collection deletion or destructive database rollback is needed. The separate mobile isBeta UI masking flag is not the invitation switch.

Verify a fresh installation can reach the normal app and register without an invitation, including classic email signup and configured provider sign-in. Existing admitted accounts keep working. Keep historical invitation and admission records until a separately approved retention decision. Once supported builds no longer need the policy endpoint, removal of the dormant mobile gate and server endpoints can be a separate cleanup PR.

For an emergency rollback, disable the gate using the same procedure. Do not drop tables or delete accounts to restore access.

Validation and release evidence

Automated coverage must establish single-use redemption, idempotent retries, no recipient-email comparison, enabled/disabled policy, blocked product access, and mobile error/logout transitions. Native Apple UI and real device rendering need a manual beta test in addition to automated checks. No production accounts are modified by implementation tests.

Status at preparation: implementation and PR checks, not production activation. Refer to the linked tracking entry and PR validation results for what has actually run.

Transition follow-up: backend #643, issue #642. Read-only inspection on 3 November 2026 found the deployed policy endpoint returning 404 and the admission table absent. This is a deployment gap, not proof of an invalid account or consumed code. Do not bypass the gate on 404 or clear user data to fix it. Deploy the compatible API and apply the backed-up migrations through the approved rollout. No production deployment was performed by these PRs.

Issuing and checking a code

See the operator procedure for generation, regeneration, live-schema checks and validation without consuming an invitation.