void 0.20.0 → 0.20.2

package/skills/void/docs/guide/platform-administration.md

@@ -29,6 +29,24 @@ void platform auth status
 
 This shows your account, the session's expiry, and the features available on the platform. To end the session, run `void platform auth logout`.
 
+If the platform is protected by Cloudflare Access, `void connect <url>` handles
+the company sign-in before Void login. Interactive Access authentication uses a
+locally installed `cloudflared` and saves its short-lived credential in your
+system keychain for that platform origin. You do not need to copy browser cookies.
+
+For CI, Access credentials do not replace Void deployment credentials. A project
+owner creates the latter with `void project token create`; it is independently
+revocable, expires within 90 days, and authorizes only that project's deploy
+workflow. Human and operator tokens cannot be renewed by Access service proof.
+
+Store Access credentials in origin-keyed `VOID_ACCESS_CREDENTIALS`. A deploy
+that uses prerendering or remote bindings needs entries for both the exact API
+and proxy HTTPS origins, even when both entries contain the same admitted
+service-token pair. `VOID_ACCESS_ORIGIN` selects only one recipient and therefore
+cannot cover both calls. Keep the JSON value in your secret manager, not in
+application configuration. See [CI deployment setup](./self-hosted-platform.md#connect-and-deploy-an-app)
+for the required shape.
+
 ## Choosing a Platform
 
 If you manage more than one platform, list your connections and choose a default:
@@ -46,9 +64,64 @@ void platform user list --connection <connection-id>
 
 Use an ID or URL from the connection list. Administrative commands use this selection even when you run them inside an app with a different deployment destination.
 
+## Recovering Administrator Login
+
+If no administrator can use the configured identity provider, the installation
+owner can recover an existing administrator with Cloudflare management access,
+direct database access, and the original encrypted recovery credentials:
+
+```sh
+void platform config auth recover company --installation <id> --file recovery.json
+```
+
+The file identifies the existing account, for example
+`{"administratorUserId":"existing-admin-id"}`. Recovery opens a real login test
+and asks you to confirm the exact identity before restoring access. It does not
+create a new administrator. To use a replacement provider, include its nonsecret
+`configuration` with a new connection ID and supply the secret through
+`--client-secret-env <name>`. To rotate an existing provider's secret, keep its
+connection ID and identity configuration.
+
+For `--yes`, also pin `expectedIdentity` with the exact `issuer` and `subject` in
+the file. A successful browser login is still required. Use `--plan` to preview
+the affected administrator and connection before starting recovery.
+
 ## Giving People Access
 
-A newly installed platform restricts signup to approved identities. To let a teammate join with GitHub, add their login to the allowlist:
+Open **Settings** in the administrator UI, or run `void platform config auth`,
+to add, test, enable, or disable login methods. Access protection and login
+methods are separate settings. A provider test shows the authenticated account
+before you explicitly link it or enable the configuration.
+
+To change the company gate after installation, use the installing workstation
+with its saved recovery credentials:
+
+```sh
+void platform config auth protection show
+void platform config auth protection enable --installation <id>
+void platform config auth protection disable --installation <id>
+```
+
+Enabling offers application creation or connection to an existing application.
+It checks every API, proxy, and configured dashboard origin and requires a company
+user sign-in. Changing protection ends all current human sessions; sign in again
+afterwards. Before removing a gate used for company signup, select another
+verified company rule or restricted signup. Removing protection retains the
+Cloudflare applications for deliberate cleanup. Disabling an Access login method
+does not remove the gate.
+
+Users can add another enabled login to their existing account with
+`void auth link <connection-id>` or **Account** in the optional
+dashboard. Sign in again first if prompted, then authenticate with the additional
+provider and confirm the identity shown. Matching email addresses alone do not
+link accounts.
+
+For company installations, choose **Company-approved users** under **Who can
+join?** to create accounts automatically for users accepted by your configured
+company rules. Individual invitations are not required. Invited/allowlisted
+signup remains available when you need to approve people individually.
+
+With invited/allowlisted signup selected, let a teammate join with GitHub by adding their login to the allowlist:
 
 ```sh
 void platform signup allow github teammate
@@ -65,6 +138,14 @@ void platform signup allow email '*@example.com'
 
 Email patterns apply across the platform's sign-in providers. Quote a domain pattern so your shell passes the `*` to Void.
 
+For an OIDC login without a verified email, allow the identity by its login connection and stable provider subject instead:
+
+```sh
+void platform signup allow identity company-sso 'Employee-42'
+```
+
+Use the connection ID shown by `void platform config auth list` and the exact subject reported by your identity provider. The match is case-sensitive and does not infer an email address or link another account. Any domain or group restrictions configured for that login method still apply, and the account joins as an ordinary user. Remove the grant with `void platform signup disallow identity company-sso 'Employee-42'`.
+
 To invite someone else by email, use:
 
 ```sh
@@ -83,7 +164,7 @@ void platform invitation list
 Invitation history remains available after an involved account is removed. The stored actor ID
 remains visible when that account's login no longer exists.
 
-`void platform signup open` allows anyone to sign up. Use `void platform signup restrict` to require an allowlist match again. Removing an allowlist entry affects future signup; it does not suspend an existing account.
+`void platform signup open` allows anyone to sign up. Use `void platform signup restrict` to require an allowlist match again. Disallowing an entry affects future signup; it does not suspend an existing account.
 
 ## Managing Users and Projects
 
@@ -104,6 +185,19 @@ void platform project show <project-id>
 
 Project details include resources, domains, and recent builds and deployments. The [command reference](../reference/cli.md#operator-commands) also covers suspending and restoring users, deleting projects, and removing accounts.
 
+### Transferring Project Ownership
+
+Only an installation administrator can change a project's owner. The new owner must already have an account on this platform. Preview the transfer before applying it:
+
+```sh
+void platform project owner <project-id> <new-owner-user-id> --plan
+void platform project owner <project-id> <new-owner-user-id> --yes
+```
+
+The preview shows both owners, their plans and suspension state, active work that blocks the transfer, and the changes to routing and usage counters. Wait for or cancel any active deploy, rollback, or build before retrying.
+
+After the transfer, the former owner becomes a project administrator. Existing project-scoped CI deploy credentials are revoked; create replacements as the new owner. The new owner's plan and limits apply immediately. Usage before the transfer remains charged to the former owner; later usage is charged to the new owner. If an apply reports partial convergence, inspect the project and operator event log before repeating it.
+
 New users on a self-hosted installation start with the `custom` profile, which
 does not cap application requests, AI usage, deployment frequency, or retained
 Worker deployments. Named profiles such as `pro` apply the platform's quota and
@@ -121,6 +215,122 @@ before changing application traffic or deleting resources. If cleanup fails,
 access stays revoked and the error describes the partial result. A remaining
 administrator can inspect it and retry cleanup.
 
+## Managing Email
+
+These commands apply to a platform that enables email. Every project can send from and receive at `<slug>+tag@<mail domain>` on the platform's shared mail domain; the [email guide](./email.md) describes what applications do with that.
+
+### Deciding who mail may reach
+
+By default, mail from the shared sender reaches only the recipients each project has verified. For a team whose applications mainly mail colleagues, widen that once for the whole installation:
+
+```sh
+void platform email policy
+void platform email policy-set domains --domains example.com,corp.example.net
+void platform email policy-set any
+void platform email policy-set verified
+```
+
+`domains` lets every project mail any address on the listed domains in addition to its verified recipients; `any` lifts the check. Cloudflare still refuses a recipient it has not verified until your mail domain is onboarded for Email Sending, which needs Workers Paid on the platform's account. Until then such sends come back as `UNVERIFIED_DESTINATION` for that recipient, whatever the policy says. Two things the policy never changes: sends from a project's own custom domain, and mail to any address on the platform's own mail domain — those stay verified-recipient-only, so no project reaches another project's inbox without its consent. A tightening applies to new send admissions as soon as it commits; previously admitted attempts may finish. The same setting is on the admin UI's **Email** page.
+
+### Project caps
+
+Each project has 200 recipient submissions per UTC calendar month and 10 in a rolling 60-second window by default. An attempt stays charged once it starts, including a failed or uncertain outcome. Raise or lower a project's caps by id or slug:
+
+```sh
+void platform email limit hr-portal --monthly 2000 --burst 30
+```
+
+The project's page in the admin UI shows the current values and clears an override.
+
+### Recovering an interrupted send
+
+If a sender stops after beginning a provider call, its unresolved attempt blocks
+removal of the project or sender domain. Inspect the attempt ID and start time:
+
+```sh
+void platform email attempts --project hr-portal
+```
+
+First confirm that the original execution has ended through your Worker logs or
+incident records. Once the attempt is at least 24 hours old, resolve it with an
+audit reason that contains no recipient address or message content:
+
+```sh
+void platform email attempt-resolve <attempt-id> --ended --reason "Original Worker execution ended; provider outcome could not be verified" --plan
+void platform email attempt-resolve <attempt-id> --ended --reason "Original Worker execution ended; provider outcome could not be verified"
+```
+
+This records the send as `outcome_unknown` and releases its cleanup fence. The
+attempt remains charged and is never retried. If its 30-day delivery record has
+expired, only its recipient-free fence is removed. Do not resolve an attempt
+while its original execution may still be active.
+
+Inspect a project's retained receipt and recipient outcomes with:
+
+```sh
+void platform email logs hr-portal --page 1 --limit 50 --json
+```
+
+Logs include operation IDs, recorded outcomes, provider references, and error codes.
+After project deletion, use its project ID until the 30-day metadata retention
+period expires. Message bodies, subjects, attachments, and credentials are not logged.
+
+### Registering email domains for projects
+
+Your users may hold no Cloudflare account. Tell the platform that administrators register email domains, so `void email domain add` prints the command to ask you for instead of opening a token-creation page:
+
+```sh
+void platform email settings-set --domains admin
+```
+
+Then register a domain for a project. The zone must be in the platform's Cloudflare account; the platform's own credential does the setup, and no Cloudflare credential is stored per domain:
+
+```sh
+void platform email domain-add mail.example.com --project hr-portal
+void platform email domain-status mail.example.com
+void platform email domain-rotate-secret mail.example.com
+void platform email domains
+```
+
+Name the exact mail domain: a subdomain such as `mail.example.com` when the apex already receives mail, otherwise the apex itself. `domain-status` reports inbound, outbound, and management readiness separately. Follow any required DNS or Cloudflare dashboard step, then use `domain-sync` to reconcile. Use `domain-rotate-secret` when you need to replace the zone ingress credential explicitly. Email Sending onboarding needs Workers Paid; after upgrading, `domain-sync` re-attempts it. For a zone in another Cloudflare account, pipe an API token for that account on standard input:
+
+```sh
+void platform email domain-add mail.other.example --project hr-portal --token-stdin --yes < token.txt
+```
+
+Project owners see administrator-registered domains in `void email domain list` and `status`; `status` names the `void platform email` command for any step they cannot take themselves, and `sync` and `remove` point them at `domain-sync` and `domain-remove`. A domain an owner registered before you switched to `admin` stays theirs to renew, sync and remove. The runtime token needs the email permissions listed in the [self-hosting guide](./self-hosted-platform.md#runtime-token-permissions) for this to work.
+
+A permission refusal leaves setup blocked. After correcting it, run `domain-sync`
+to resume that same setup operation; repeat `domain-rotate-secret` to resume a
+blocked rotation without replacing its staged secret. If project deletion leaves
+a blocked domain cleanup, correct the permission and run `domain-remove <domain>`
+to finish the retained cleanup. If its token has expired or been revoked, provide
+a replacement scoped to the same account and zone:
+
+```sh
+void platform email domain-remove mail.other.example --token-stdin --yes < token.txt
+```
+
+This recovery is available only after project deletion has begun and no other
+project uses the connection. For a live project, renew its token through
+`domain-add`. A timed-out Cloudflare
+mutation stays stopped because replay may duplicate a provider write. After
+confirming the original execution ended, wait 24 hours, inspect the exact
+routing, Worker, secret, catch-all, or Sending resource named by the preview,
+and use its recovery fence:
+
+```sh
+void platform email operation-resolve <operation-id> --ended --outcome <applied|not-applied> --reason "Provider state verified" --plan
+void platform email operation-resolve <operation-id> --ended --outcome <applied|not-applied> --reason "Provider state verified"
+```
+
+Run recovery with the same platform version that created the persisted intent.
+`applied` continues without replaying the write; `not-applied` permits that exact
+step to retry. Secret rotation keeps its staged generation, and removal resumes
+from the unresolved cleanup step. Age alone never authorizes a retry.
+
+Register administrator domains only after a platform upgrade has completed, and remove them before rolling the platform back to a version that predates this feature: an earlier runtime cannot use the platform credential for them and does not distinguish administrator-registered domains from owner-registered ones.
+
 ## Previewing Changes
 
 Commands that change the platform show the affected objects before asking for confirmation. To inspect a change without applying it, add `--plan`:
@@ -210,3 +420,5 @@ unset VOID_OPERATOR_TOKEN
 Disable shell tracing for the exchange and do not write either token to logs or plaintext files. A full API login session expires after 30 days and can be revoked sooner; renew it through the normal authenticated login flow and update the protected CI secret. A job that runs longer than one hour must repeat the exchange while its full API session is still valid. An expired operator token cannot refresh itself, and Void does not issue permanent service tokens for administrator automation.
 
 `auth login --token-stdin` performs the same elevation and saves the one-hour operator token in the system keychain for interactive use. See [operator authentication](../reference/cli.md#operator-authentication) for the full command syntax.
+
+An email zone has one connection and ingress Worker shared by its exact domain assignments. Removing one assignment preserves resources used by the others. The Email administration page can explicitly rotate that connection secret; ordinary synchronization does not rotate it. Setup and cleanup outcomes include operation IDs, and uncertain provider writes remain recorded until reconciled.

package/skills/void/docs/guide/platform-development.md

@@ -83,7 +83,18 @@ CF_ACCESS_APP_URL=https://platform.example.com
 SITE_DOMAIN=apps.example.com
 ```
 
-The helper refreshes an Access session before the dev server starts. A configured `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET` pair can be used for automation instead. This is dashboard development configuration; Access credentials are separate from platform login credentials.
+The helper refreshes an Access session before the dev server starts. Human
+dashboard requests require the user's Access session as well as their Void login;
+a service token does not represent that user. Service-token pairs are for scoped
+machine operations. This is dashboard development configuration; Access
+credentials are separate from platform login credentials.
+
+For a deployed dashboard, bind its `API` service to your platform API, configure
+`DASHBOARD_URL` on both the dashboard and API, and include that exact dashboard origin in the
+platform's Access protection application. The dashboard passes the browser's
+company identity to the API using that service binding. Its login page shows
+the platform's currently enabled methods, and **Account** supports adding an
+additional login identity.
 
 ## Testing Changes
 
@@ -144,6 +155,57 @@ void-dev platform upgrade <installation-id> \
 
 Then run it without `--plan` to apply the upgrade. Source-built runtimes go through the same artifact, database, ownership, and health checks as released runtimes. The CLI preserves a disabled installation's state and records the source revision in its installation checkpoint.
 
+## Optional GitHub Webhook Ingress for Access-Protected APIs
+
+The core installer does not deploy the dashboard, GitHub App, build Containers,
+or webhook ingress. If a source-built installation adds those optional services
+and Cloudflare Access protects its API hostname, GitHub cannot deliver directly
+to `/webhooks/github`: GitHub does not present your Access credentials. Do not add
+an Everyone or bypass policy to the API application.
+
+The API source package includes an optional, path-isolated Worker for this case.
+It accepts only `POST /github`, validates GitHub's signature over the raw body,
+and forwards one authenticated internal operation over an API service binding.
+The API independently verifies both that internal proof and GitHub's signature
+before running the normal webhook handler. Installations without perimeter
+protection can continue using the API's direct `/webhooks/github` endpoint.
+
+To deploy the optional ingress:
+
+1. Deploy the source API/build runtime containing the internal operation and its
+   build bindings, then finish the separate GitHub App/build-service
+   configuration. A core install or upgrade alone does not add managed builds.
+   Enable the platform's managed-build capability only when that infrastructure
+   is ready.
+2. Edit `platform/packages/api/wrangler.github-webhook-ingress.jsonc`. Give the
+   ingress a name unique to the installation and set its `API` service binding to
+   the exact installed API Worker name. Keep its public hostname separate from
+   every human/API hostname covered by Access.
+3. Deploy it from the repository root:
+
+   ```sh
+   vp run --filter @voidcloud/api deploy:github-webhook-ingress --env production
+   ```
+
+   Use `--env staging` for the staging entries in the same config.
+
+4. In the Cloudflare dashboard, add encrypted Worker secrets. Set the GitHub
+   App's existing `GITHUB_WEBHOOK_SECRET` on both the API and ingress Workers.
+   Generate a separate high-entropy value, such as `openssl rand -base64 32`,
+   and set it as `GITHUB_WEBHOOK_INGRESS_SECRET` on both Workers. Do not reuse a
+   platform management, JWT, Access, or GitHub webhook credential for that value.
+5. In the GitHub App settings, keep **Content type** set to `application/json`,
+   keep the same webhook secret, and change **Webhook URL** to the isolated
+   ingress URL ending in `/github`. Use GitHub's test delivery and confirm a 2xx
+   response before relying on push builds.
+
+The ingress has no login, dashboard, project, operator, proxy, or arbitrary
+forwarding route. It does not make the GitHub integration part of the core
+installer, provision build executors, create a GitHub App, configure Cloudflare
+Access, or manage either Worker's secrets. Its body limit is 25 MiB, based on
+GitHub's [documented 25 MB webhook payload cap](https://docs.github.com/en/webhooks/webhook-events-and-payloads#payload-cap);
+malformed or larger deliveries are rejected before event processing.
+
 ## Deploying Source Builds from CI {#source-build-ci}
 
 Build `@void/platform` from your checkout and pass its runtime directory to `install`, `upgrade`, `repair`, `enable`, or `rollback` with `--runtime`. Custom runtimes get the same integrity, migration, health, and rollback checks as packaged releases.
@@ -169,7 +231,7 @@ node packages/void/dist/cli/cli.mjs platform upgrade "$VOID_PLATFORM_INSTALLATIO
 
 Omit the installation selector only if the account has one discoverable installation. Run one deployment per installation at a time, and let it finish before starting the next. Cancelling during migrations or Worker rollout can leave an installation waiting for recovery.
 
-Keep the management token, database URL, JWT signing secret, and complete project-encryption keyring in a protected CI environment. Upgrades inherit deployed Worker secrets. The original values are needed when recreating a missing Worker; configuration credentials are also needed when explicitly rotating them.
+Keep the management token, database URL, JWT signing secret, email signing secret for email-enabled installations, and complete project-encryption keyring in a protected CI environment. Upgrades inherit deployed Worker secrets. The original values are needed when recreating a missing Worker; configuration credentials are also needed when explicitly rotating them.
 
 :::
 
@@ -232,4 +294,33 @@ Publishing requires both SDK CI and platform CI, including the platform unit and
 API integration suites. Release tags also run the Windows SDK checks; a passing
 SDK-only build cannot publish a changed control plane.
 
+### Retrying a Release
+
+To retry a failed release without moving an existing tag, add `+retry.N` to a
+new Git tag, with `N` starting at `1`. Keep the package versions unchanged:
+
+| Git tag                  | Package version | npm channel |
+| ------------------------ | --------------- | ----------- |
+| `v0.21.0`                | `0.21.0`        | `latest`    |
+| `v0.21.0+retry.1`        | `0.21.0`        | `latest`    |
+| `v0.21.0-beta.1+retry.2` | `0.21.0-beta.1` | `beta`      |
+
+For example, when the packages are at `0.21.0`, commit the release fix and tag
+that commit:
+
+```sh
+git tag -a 'v0.21.0+retry.1' -m 'Retry 0.21.0 publication.'
+git push origin 'refs/tags/v0.21.0+retry.1'
+```
+
+The retry suffix belongs only in the Git tag, not in `package.json`. A `-1`
+suffix is a distinct prerelease version, not a retry. Tag and package versions
+are checked before dependency installation and the full CI jobs; retries still
+run the normal release checks.
+
+Retries publish only package versions that are still missing from npm. They
+cannot replace an already-published version. If an earlier attempt partially
+published the release and you changed its package contents, bump the version
+instead of combining different contents under the same version.
+
 For implementation history, use the design archive at `platform/meta/design-docs/README.md`. Its proposals explain earlier decisions; the source and current guides define the supported behavior.

package/skills/void/docs/guide/project-collaboration.md

@@ -0,0 +1,94 @@
+---
+outline: deep
+---
+
+# Project Collaboration
+
+A project hosted on a Void platform can have one owner and additional readers, collaborators, and project administrators. Team access is a platform feature; it is not available for projects deployed directly to Cloudflare.
+
+## Roles
+
+| Role                  | Access                                                                                                                    |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Reader                | View the project, usage, resources, deployments, builds, logs, and member roster. Cannot deploy.                          |
+| Collaborator          | Reader access plus deploy, rollback, cancellation, migrations, secrets, database configuration, and deploy prerequisites. |
+| Project administrator | Collaborator access plus domains, email destinations, GitHub configuration, invitations, roles, and member removal.       |
+| Owner                 | Project administrator access plus project deletion.                                                                       |
+
+Only the owner can create, list, renew, or revoke the project's CI deploy
+credentials. Those credentials run unattended deployments as the billing owner
+and remain independent of a member's login session, so collaborators and
+project administrators deploy with their own account instead of minting a
+durable owner credential.
+
+The owner's plan, limits, and suspension state govern the project. A member's
+own plan does not change the project's available usage, and acting through a
+collaborator does not bypass an owner suspension. A project administrator is
+not an installation administrator and receives no platform-wide access.
+
+## Invite a Registered User
+
+An owner or project administrator can invite someone by the email address registered to their existing account on the same platform:
+
+```sh
+void project team invite teammate@example.com --role collaborator
+```
+
+Pass `--project <slug>` to manage a project other than the linked project. An unknown email is rejected. A project invitation neither creates an account nor adds the address to a restricted-signup allowlist.
+
+Invitations expire after seven days. If the platform cannot send invitation
+email, the CLI prints the invitation ID and connection and acceptance commands
+to share with the invited user. The invitation also appears when that user runs
+`void project team pending` on the same platform.
+
+List the roster and sent invitations with:
+
+```sh
+void project team list
+void project team invitations
+```
+
+## Respond to an Invitation
+
+Connect to the platform from your invitation, then see invitations addressed to
+your account and respond using the invitation ID:
+
+```sh
+void connect https://api.example.com
+void project team pending
+void project team accept <invitation-id>
+# or
+void project team decline <invitation-id>
+```
+
+An invitation is bound to the registered account. Forwarding its ID does not let another user accept it.
+
+These three commands use the active platform connection selected by
+`void connect`, even inside a directory linked to another project or deployed
+directly to Cloudflare. `VOID_API_URL` takes precedence when set. If you use
+`VOID_TOKEN`, set `VOID_API_URL` to the matching platform; a token without that
+URL selects Void Cloud. Each command shows the platform it contacts.
+
+Accepting an invitation grants access without linking your current directory.
+Open the invited application's directory and run `void project link` if it is
+not linked yet. If it is already linked to another project, use a separate
+checkout without `.void/project.json`, connect to the invited platform there,
+and run `void project link`.
+
+If the invitation is missing, check the platform and signed-in account. To
+switch accounts, set `VOID_API_URL` to the invitation's platform URL, unset
+`VOID_TOKEN` if present, then run `void auth logout` and `void auth login` using
+the invited email address. For an expired or revoked invitation, ask a project
+administrator to invite you again.
+
+## Change or Remove Access
+
+Owners and project administrators can change any non-owner member or revoke a pending invitation:
+
+```sh
+void project team role <user-id> reader
+void project team remove <user-id>
+void project team revoke <invitation-id>
+```
+
+A non-owner member can leave with `void project team leave`. The owner cannot leave; an installation administrator must [transfer ownership](./platform-administration.md#transferring-project-ownership) first.