Skip to content

[Sites] Register external applications with scoped access and environments #2104

Open

Description

@sidneyswift

Parent epic: #2093

Priority

P0 — First shared Sites and external Widgets release.

User journey

An app owner connects their building agent to Recoup → registers an application and verified production/preview origins → receives installation configuration → revokes access when necessary.

Acceptance criteria

  • Create application resources owned by an authenticated workspace, with development/production environments, exact allowed origins, provider configuration references, and explicit billing owner. Do not require a Site resource.
  • Separate owner credentials, delegated building-agent scopes, publishable application identifiers, and short-lived fan sessions. Never put customer secret keys in generated frontend code.
  • Domain allowlisting controls embedding, not authorization to incur arbitrary charges. Define the hosted bootstrap flow for static websites and server-backed applications.
  • Support credential rotation, application suspension, environment-specific quotas, and access revocation; keep sessions and customer data isolated by application and tenant.
  • Expose create/read/update/revoke operations through the same API/MCP domain functions, with validated inputs and documented errors.

Blocking dependencies

None. This foundation ticket can start now.

These are completion prerequisites, mirrored in GitHub’s blocked-by links. Design and contract work may start earlier. Other coordination references are not blockers.

Validation

Test two unrelated customer apps, preview versus production, spoofed origins, expired/revoked sessions, secret exposure, and cross-tenant access.

Delivery conventions

API owns business logic and billing; HTTP and MCP share it. Chat/embeds/SDKs are clients. Database changes use the database repository PR workflow. Update marketing-owned docs and generated indexes. Use Vercel Workflows for new durable background work. No automatic publication or unbounded customer spending.

Callback registration responsibility

Customer production/preview origins and permitted return destinations are application configuration in Recoup. Authorized API/MCP setup must support adding and revoking exact addresses without manual Spotify callback edits. Bind registrations to the correct application and environment; do not permit broad shared-builder-domain wildcards. The provider callback itself stays on Recoup. See #2107 for the connection flow.

Pro usage policy acceptance

Application/site usage must roll up to one authenticated billing customer across environments and sites. Coordinate quota ownership and suspension with #2105; creating another site/application must not reset allowances. Read the approved Pro usage and overage policy in epic #2093.

Council-approved ownership and abuse requirements

  • Bind allowances and purchases to the paying account/organization; changing site creator or creating another app cannot reset usage. Keep separate clients isolated.
  • Only authorized billing members can enable top-ups or increase the spending ceiling. Public app identifiers/fan credentials cannot authorize purchases.
  • Register widget origins and issue short-lived sessions; origin checks alone are not proof of legitimate traffic. Coordinate per-customer admission/abuse limits with [Sites] Meter Sites operations with credit reservations and spending limits #2105.
  • Distinguish campaign restriction from essential returning-user identity access; application suspension/security revocation remains a separate reason to deny access. Follow epic [Epic] Sites: shared Fans API, embeddable Widgets, and release campaigns #2093's approved policy.

Inactive parent transaction candidate — November 17, 2026

Database #138 is DRAFT, unmerged and unapplied, exact head df7be4c65b98924373b38c7d257f4b1c1820d6b7. Seven files under proposals/application-registration-2104/ propose atomic application/initial-environment/origin creation with immutable registration receipts, explicit creation entitlement and separately scoped management permissions. There is no Site dependency or implicit post-create management grant. Personal-workspace classification/policy is an explicit disposable-test assumption, not adopted customer policy.

Independent source and final runner reviews passed. Disposable PostgreSQL15/17 each passed18 focused cases, covering tenant/environment/operation denials, authorization before replay, idempotency conflicts, rollback, creation expiry after observed lock waits, revocation serialization, exact existing proof/configuration composition and disabled outputs. Three cleanup fault controls passed. The runner uses an explicit minimal environment and UTF8; failed intermediate cleanup evidence is retained and its owned cluster was stopped. Post-create management has explicit revocation only; time-based management leases are not implemented.

No automatic migration, workflow, runtime grant, credential verifier, public route, DNS/provider call or bootstrap activation was added. Supabase Preview reports skipped. Existing PR workflows run separately and do not execute these18 new local tests. SQL does not authenticate caller UUIDs: actual original-actor verification remains the trusted server adapter's prerequisite. All returned activation/production flags remain false.

This prepares the missing parent transaction for review. It does not complete registration availability, approve enrollment/personal or organization policy, qualify deployed least-privilege execution, select retention/deletion terms, authorize a pilot or satisfy native/shared Fans-and-Widgets acceptance. All original criteria remain open.

Unwired API adapter source merged

API #1269, exact head 34470f6b51032cb1cd1ef4a3fd56bcac2fff8d93, merged as 38ee9828635881526ac9f8b304626739ef1813f8 with the tested tree b5a7a529022c2fa5754f02080412674b6a78f971. It adds internal create/read orchestration against the exact proposed Database138 contract. It uses actual existing-account REST authentication with original-actor/self/no-organization checks, the existing canonical validator, required injected storage and strict disabled receipt bindings. Valid uppercase read UUID selectors are canonicalized to PostgreSQL's lowercase form; altered returned IDs are rejected. Unknown outcomes retain the original operation/key/input; no automatic retry or second ledger is added.

Final controlled qualification passed45 adapter tests after composing accepted API1268; the earlier composition also passed12 incoming expiry regressions. An actual disposable SQL creation/read receipt anchors the parser and preserves timestamp precision/UTC text. Independent final-head source review and all11 final check/status contexts passed; all12 review threads were resolved. The dedicated controlled Node22 job checked out the exact head and passed45 tests. Ordinary Unit CI passed10026 tests with70 skipped on a synthetic merge whose tree equals the candidate. Normal-main Unit44231078934, MCP OAuth compatibility44231079013 and strict accounting types44231078910 all passed at merge38ee9828. Production deployment metadata is READY for that exact merge and the canonical alias points to it; a standard-TLS unauthenticated landing GET returned200 without redirects. These are separate source/CI/deployment/public-reachability receipts; no authenticated adapter or customer acceptance is claimed. Ordinary Unit tests exclude this suite and are not its evidence.

The helper is unwired: no public route, registered MCP tool, concrete storage factory, hosted RPC, runtime grant or policy activation is added. Synthetic HTTP/MCP-shaped arguments do not prove real MCP authentication. Current MCP original-actor/nonprovisioning handoff, personal enrollment, transaction entitlement, least-privilege storage execution, retention and native/shared runtime acceptance remain separate. Database138 stays draft/unmerged/unapplied; this issue stays open.

Disposable domain-to-SQL composition source merged

API #1271, exact head 988263d81600afd77123cbf23496104ad04b04ee, merged as 18a67850b51f4845eef33bc2ee2be95ca747ad59 with candidate-identical tree 60b268283e33b5822894b046bb0c30991c9e5949. Eight test-only qualification paths join the actual create/read domain functions to the exact inactive Database138 proposal, using one parameterized SQL function call per storage operation.

Local PostgreSQL15.10/17.7 each passed8 cases on Node24.18.0: exact disabled receipts, explicit read authority, actor/environment/receipt isolation, committed-response loss and original-key replay, revocation/fresh authentication and conservative unknown outcomes for generic SQL errors. Source-drift, network and initialized-worker cleanup controls passed; independent final source review and all required PR checks passed, with12 review threads dispositioned. Separate Node22 CI passed61 existing controlled adapter/MCP tests and10026 ordinary tests with70 skipped. Ordinary CI excludes the new SQL composition suite; its Node22 execution remains untested. The isolated loader diagnostic used Node23.6.1 and is separate evidence.

This is a disposable qualification harness, with no production factory, route/tool registration, runtime wiring, enrollment or policy activation. Database138 remains draft, unmerged and unapplied. Normal-main Unit44239481922, strict accounting types44239482255 and MCP OAuth compatibility44239481889 all passed at exact merge18a67850. Production metadata is READY for that merge and the canonical alias points to it; an unauthenticated landing GET returned200 with standard TLS and zero redirects. These separate metadata/reachability receipts do not establish a hosted registration operation. All original acceptance criteria remain open; no hosted registration or customer availability is established.

Unregistered MCP composition source merged — API1272

API1272 merged reviewed head 2606c910 as f8ec0bee with the tested tree unchanged. The inactive composition uses the original request with the real SDK and existing-actor/domain contracts; controlled exact-head Node22 CI passed 128 cases. Independent review, required checks and 13 review dispositions completed before merge. Media admission now parses case-insensitive types and Accept quality exclusions; lifecycle coverage distinguishes actual domain completion from an SDK response promise. No public route/tool registration, production storage factory, Database merge/apply or customer availability was activated. Exact-merge normal-main Unit44244581236, strict types44244581219 and compatibility44244581186 passed. Production metadata reports READY for f8ec0bee and its canonical alias; the unauthenticated landing GET returned200 with standard TLS and zero redirects. These receipts do not establish MCP runtime behavior; intended-account/native acceptance remains separate. Original acceptance criteria remain open.

Conflict contract qualification source merged — API1273

API1273 merged reviewed head 947c9fb4 as ec284cba, preserving the tested tree. The inactive descriptor/golden and disposable joined harness now bind the reviewed conflict-contract proposal: exact create conflicts are distinct from denial and unknown outcomes, with original-key recovery and immutable history preserved. Exact-head Node22 CI passed130 controlled cases; separate local Node24 qualification passed12 joined cases each on PostgreSQL15/17. Independent source review, required checks and both remote review dispositions completed before merge. The Database proposal remains draft and unapplied. This is source/qualification delivery, not a production SQL factory, public registration activation or hosted acceptance; exact-merge normal-main Unit44247724962, strict types44247724974 and compatibility44247725041 all passed. Production metadata reports READY for ec284cba with the canonical alias; the unauthenticated landing returned200 with standard TLS and zero redirects. These metadata/reachability receipts do not establish authenticated registration. Original criteria remain open.

Restricted SQL adapter source merged — API1274

API1274 merged reviewed head caaa1b5835a92ce6ae985ca446aa359147117899 as eac1ed9a35824be60d84b26c35a40cdf15c90e5d. Unwired create/read helpers accept an existing SQL client and use fixed parameterized calls through the disposable restricted execution wrappers. Proposal-local validation rejects NUL and malformed UTF-16 before storage, preserving valid keys and existing name trimming. Controlled qualification passed145 tests; actual restricted domain/helper/SQL/MCP SDK qualification passed30 tests each on PostgreSQL15/17 with successful bounded cleanup. Earlier PG17 machine-timeout receipts were retained and the original fixture's cleanup verified before the successful normal-guard rerun. Independent reviews and all11 exact-head checks passed; the coordinator dispositioned the unchanged-baseline CodeRabbit warning using actual merge-base/blob evidence.

Exact-merge normal-main Unit44290853502, strict types44290853234 and compatibility44290853321 passed, including their individual steps. Git-triggered production deployment metadata is READY at exact merge eac1ed9a, and api.recoupable.dev resolves to that deployment; an unauthenticated landing GET returned200 with standard TLS and no redirects. These source/CI/deployment/public-reachability receipts do not establish authenticated registration or activate a production SQL factory, runtime grant, Database apply, public route/tool, enrollment or customer availability. Intended-account/native gates and all original acceptance criteria remain open.

Activity

  1. added
    priority:P0Required for the first shared Sites and external Widgets release
    on Sep 19, 2026
  2. sidneyswift commented on Nov 6, 2026

    @sidneyswift
    CollaboratorAuthor

    Shipped so far: a preflight that checks a proposed application (origins, return URLs, environments, billing owner) without saving it (recoupable/api#1136, recoupable/marketing#235), a domain-proof proposal (recoupable/api#1189), and disabled offline rehearsals of the proof and configuration transactions (recoupable/api#1191, recoupable/api#1197, recoupable/database#128, recoupable/database#131).

    Nothing is saved or switched on yet: no application records, credentials, fan sessions, rotation, suspension or revocation, and no live domain proof. All acceptance items remain open.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:P0Required for the first shared Sites and external Widgets release

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions