stech / agent control planev0.18.1
stech/
Account

Maestro Connect sign-in

Stech accepts Maestro Connect as an optional OIDC sign-in provider. Standalone password and magic-link accounts continue to work. A connected organization keeps its Stech ID, workspaces, local roles, billing and settings.

Registration and workspace invitations #

New Stech users return from Maestro sign-in (including Google inside Maestro) to /onboarding, where they choose Create a workspace or Join a workspace. Email/password registration uses the same choice. Invitation destinations survive sign-in/sign-up switching and OAuth; a supplied invitation is preselected for review. Users can paste the Stech invitation code or full link. Acceptance checks the existing invitation rules, then selects that workspace before opening Stech. If selecting the workspace fails, Open workspace retries selection without consuming the invitation again. Existing automatic personal organizations remain available for compatibility; this flow does not delete or repurpose them.

Maestro identity and workspace membership are separate. A standalone Stech workspace accepts Maestro-authenticated users through ordinary Stech invitations; it does not require or create a Maestro organization. Owners can explicitly connect an organization later in Settings → Maestro Connect. A connected workspace requires live membership in the bound Maestro organization as well as the existing installation checks. Its administrator must also invite the person in Maestro. Stech's current profile grant does not authorize creating Maestro invitations or assigning Maestro roles. Matching organization names never establishes a binding. Stech roles control Stech actions; Maestro scopes govern consented Maestro access.

Setup #

Register Stech in the Maestro developer portal. The owning account is [email protected]. Use the normal application approval flow so the ACTIVE app is available to other organizations to install; do not restrict it to Cem's organization or add a privileged first-party client.

  • Homepage: https://app.stech.com
  • Production redirect: https://app.stech.com/api/proxy/v1/auth/oauth2/callback/maestro
  • Login scopes: openid profile email offline_access
  • Public client, authorization code + PKCE S256; no client secret.
  • Stech requires organizations to install the app organization-wide, with profile consent. A brand-only installation does not authorize a whole Stech tenant. Maestro's separate requiresInstallation flag gates its proxy/data-source routes; this auth-only app declares none and enforces installation in Stech itself.
  • Create an app-owned server API token with profile permission. The current portal inherits the app's four approved OIDC scopes and offers no narrower token selector. Do not add admin or unrelated API scopes. Its only use in Stech is reading /api/v1/apps/{appId}/installations.

Set these API runtime variables through the existing secret/config deployment mechanism. No provider credentials belong in browser environment variables:

STECH_MAESTRO_CLIENT_ID=app_...
STECH_MAESTRO_APP_ID=...
STECH_MAESTRO_INSTALLATION_TOKEN=mh_live_...
STECH_APP_URL=https://app.stech.com

All three Maestro values are required together. Unset values disable the login button; partial configuration fails startup. Apply migration 0046_maestro_organization.sql before starting the new API. It adds one nullable, unique organization binding, with no data rewrite or workspace mutation.

For local testing with an approved app, register the exact local callback, for example http://localhost:6555/api/proxy/v1/auth/oauth2/callback/maestro, and set STECH_APP_URL accordingly. A DRAFT client does not support the full refresh-token and installed-organization flow; complete normal app approval first. Unit/contract fixtures require no live registration.

For Cem's existing organization:

  1. Sign in to the existing Stech account using its existing method.
  2. Open Settings → Maestro Connect, link the Maestro account and finish the provider consent flow. The email addresses may differ; the existing Stech account and email are preserved.
  3. Choose Install Stech for the Maestro organization and consent to organization-wide profile access. An existing verified installation skips this step.
  4. Select the Maestro organization and Link existing organization. The caller must be an active Stech owner and a Maestro organization admin in the installed org.
  5. Other members sign in with Maestro. They receive a local member role on first access unless they already have a Stech role. Local deactivations are preserved.

Other Maestro organizations can install the approved app, sign in, and choose a new Stech organization or link one they already own. There is no email-domain allowlist. Bindings cannot be moved or removed through a user-facing endpoint. Uninstalling in Maestro denies access but retains all Stech data for reinstall.

Security and failure behavior #

  • Better Auth owns state, PKCE, the one-use authorization-code callback, explicit account linking and Stech sessions. Existing accounts are never linked by email alone while Maestro is enabled. Authenticate the local account first. Better Auth's explicit account-linking flow permits different verified provider emails while Maestro is enabled; it still requires an authenticated local session, OAuth state/PKCE and provider authentication. A provider account already linked to another local user cannot be reassigned. The local email is retained.
  • The pinned Better Auth generic OAuth plugin does not verify ID-token signatures itself. Stech explicitly verifies RS256/EdDSA signatures through Maestro JWKS, exact issuer and client audience, expiry/issued-at, authorized party and matching live userinfo subject. Unsigned tokens and unverified emails are rejected.
  • Issuer is fixed to https://auth.maestro-connect.com; discovery/userinfo/JWKS do not come from request input. Tokens are encrypted at rest by Better Auth. Maestro access/refresh token HTTP endpoints are blocked; internal refresh is server-side. Account unlinking immediately removes connected-org access.
  • A connected org additionally requires live Maestro membership and an active org-wide installation. Stech roles remain the authority for domain permissions; Maestro organization admin is used only to authorize the initial binding. Provider membership roles ORGANIZATION_ADMIN and SUPER_ADMIN normalize to admin; BRAND_OWNER, DEVELOPER, COMPLIANCE_MANAGER and VIEWER normalize to member. Unknown role values fail closed. Global platform roles never grant organization binding authority.
  • Decisions are reused only within a single request. Neither membership removal nor uninstall waits for a Stech session or API key to expire. No mutable DB membership projection can overwrite a newer remote access decision.
  • Installation requires a same-origin POST, a Stech session and live Maestro organization-admin membership. Stech sends the user's OAuth token server-side to Maestro's fixed organization installation API with only profile consent and brandId: null. Maestro independently checks admin authority. The returned installation credential is discarded; success (including a conflict response) requires a fresh app-owned installation read proving the org-wide scope. Uninstalled memberships appear only in setup and confer no Stech tenant access.
  • Personal API keys require the owner's current Maestro membership. Organization service keys and SCIM credentials require a current org-wide installation. Stech platform-admin authority remains independent and is never assigned from Maestro claims. Internal runtime callbacks retain their existing credentials.
  • Provider failure, missing configuration, or missing account linkage denies connected-org access. Standalone organizations remain accessible. Long-running tasks already admitted are not cancelled by this login integration.
  • Boundaries include org resolvers, all bearer paths, /v1/me, CLI credential listings, device-grant draining, invitation acceptance, SCIM, Slack's OAuth callback, member linking, new Slack request admission and final Slack disclosure. Binding requires same-origin POST, both ownership proofs, a DB lock, uniqueness and an audit record. Existing local organization IDs are preserved.

Focused validation #

bun test api/tests/maestro-auth.test.ts
# Disposable local database only; fixture creates, migrates and drops its own DB.
TEST_DATABASE_URL=postgresql://[email protected]:PORT/postgres \
  bun test api/tests/maestro-auth.integration.test.ts
bun x tsc --noEmit -p api/tsconfig.json
bun x tsc --noEmit -p app/tsconfig.json

The integration fixture serves the Maestro discovery, JWKS, token, userinfo and installation contracts in process. It exercises the actual Better Auth/Hono/Drizzle flow with a real local PostgreSQL database. It is not proof of provider app approval, live consent, installation or production activation.

Deployment must use the current Stech application owner's API/environment baseline. Do not dispatch the historical full-stack workflow or overwrite protected workspace runtime/recovery configuration merely to enable this provider.

Rollback #

Keep the binding column and authorization gate after any organization has been connected. Disabling all Maestro runtime variables on this build denies access to bound tenants and leaves standalone tenants usable. Re-enable valid configuration to recover. Do not roll back to an older API that ignores bindings: that would restore local-only authorization for connected tenants. Uninstalling does not remove bindings or erase data. Binding changes are recorded as maestro.connected in the existing organization audit log; provider failures return fixed error codes without exposing tokens or provider response bodies.

edit this page on github →