[auth 4] Model platform/environment targets and platform-aware OAuth administration

[artiphishle]

Roadmap: #188

Respect the [auth] roadmap first and the AGENTS.md file of every repository touched.

Previous roadmap step

[auth 3] (#191) establishes a recoverable OAuth lifecycle and complete Web callback coverage. This issue defines which platforms/environments an app actually targets so configuration, credentials, dependencies and validation can be generated intentionally.

Repository impact

Likely:

• ankhorage/contracts
• ankhorage/studio
• ankhorage/infra
• ankhorage/ankh for doctor/readiness checks
• ankhorage/expo-runtime / ankhorage/orchestrator only where generated native/runtime planning consumes the target model

Pause at package release boundaries. Do not create a Studio-only target model disconnected from generated app/infra/build configuration.

Goal

Introduce one canonical, serializable platform and environment target model for generated apps and use it to drive platform-aware OAuth administration.

An app may support any valid combination:

Web only
Android only
iOS only
Web + Android
Web + iOS
Android + iOS
Web + Android + iOS

A project may enable another platform later without changing the stable identity of already-enabled targets.

Target model direction

The exact public contract must be designed in @ankhorage/contracts, but should express concepts such as:

type AppPlatform = 'web' | 'ios' | 'android';
type AppEnvironment = 'local' | 'preview' | 'production';

interface AppTargets {
  web?: {
    enabled: boolean;
  };
  ios?: {
    enabled: boolean;
    bundleIdentifier: string;
    scheme: string;
  };
  android?: {
    enabled: boolean;
    applicationId: string;
    scheme: string;
  };
}

Do not freeze this sketch without auditing current Expo/Infra/deployment ownership.

Environment-specific values such as local ports, production domains, signing fingerprints and provider credentials must not be conflated with the platform identity contract. Define canonical overlays/references with explicit ownership.

Requirements

Stable identities

• enabled iOS bundle identifier is stable;
• enabled Android application ID is stable;
• native schemes are deterministic, valid and stable;
• enabling a new target later does not rename existing identifiers;
• Web-only projects need not carry unused native provider dependencies/configuration.

Environment separation

Model enough environment context to distinguish:

Web local / preview / production
iOS development / preview / production
Android debug / preview / production

The model must support environment-specific OAuth callback/readiness values without storing raw secrets in the manifest.

Platform-aware OAuth administration

The Auth dashboard must derive requested setup fields from:

• enabled platforms;
• selected provider;
• selected transport capability;
• Auth backend adapter capabilities;
• environment.

Initial brokered Google OAuth requirement:

Web Client ID
Web Client Secret (trusted SecretRef)
provider callback URI display
app callback readiness display

Even when iOS/Android targets are enabled, no native Google Client IDs are required while their transport remains brokeredRedirect.

When [auth 8] later enables native transports, the same requirement model may request public iOS/Android Client IDs and platform metadata without redesigning the dashboard.

Generation planning

• generate platform sections only for enabled targets where practical;
• install/configure platform dependencies only when required by enabled capabilities;
• generated scripts/docs show relevant commands only;
• Infra derives redirect allowlists from enabled targets;
• no hidden assumption that every app is always Web+iOS+Android.

Doctor/readiness

ankh doctor must report actionable readiness by target/environment, for example:

Web local Google brokered OAuth: ready
Web production callback: missing domain
Android browser OAuth: missing generated deep-link verification
Native Google transport: not enabled

Doctor must validate configuration/capability consistency, not raw secret values.

Likely files

Contracts, non-exhaustive:

src/types.ts
src/auth.ts
src/contracts.test.ts

Studio, non-exhaustive:

src/ui/admin/pages/AuthAdminPage.tsx
src/ui/admin/pages/*Settings*.tsx
src/host/orchestrator/templates.ts
src/host/layout/*
src/manifestState.ts

Ankh/Infra/Expo Runtime paths must be identified from current ownership before coding.

Phases

Phase 1 — canonical target/environment contracts

Audit current metadata, identifiers, deployment and runtime plan contracts; define one canonical model and migration-free default for new projects.

Phase 2 — generation and Infra consumption

Drive app config, schemes, dependencies and redirect target generation from the canonical model.

Phase 3 — platform-aware Auth administration

Replace fixed provider credential forms with capability/target/environment-derived requirements.

Phase 4 — Doctor/readiness validation

Add target-specific diagnostics and impossible-combination validation.

Tests

Cover at minimum:

• every valid platform combination;
• at least one target required or explicitly documented headless exception;
• stable identifier generation and persistence;
• enable Android/iOS after initial Web-only creation without changing Web identity;
• brokered Google requirement remains one Web Client ID/Secret across enabled targets;
• disabled platforms do not request irrelevant settings/dependencies;
• local/preview/production overlay separation;
• Infra callback/allowlist target derivation;
• Doctor diagnostics for ready/missing/unsupported combinations;
• no raw secret material serialized into manifest/doctor output.

Acceptance criteria

1. One canonical platform target model exists in Contracts.
2. Any supported Web/iOS/Android combination is representable.
3. Stable native identifiers/schemes survive later target expansion.
4. Environments are distinct from platform identity and from trusted secrets.
5. Studio requests only settings required by enabled targets/transports.
6. Brokered Google OAuth uses one Web Client ID/Secret in this phase.
7. Generation and Infra consume the canonical target model.
8. Disabled targets do not add irrelevant provider packages/configuration.
9. ankh doctor provides actionable target/environment Auth readiness.
10. Behavior-focused tests, package changesets/releases and full validation pass.