Flutter client for the Gorape device trust / attestation backend. The app signs in with Keycloak (Authorization Code + PKCE), calls the Gorape OpenAPI 3.1 API with the access token, and registers a separate Gorape RP passkey through WebAuthn. The full credential/attestation response is verified by Gorape; the legacy Android Keystore registration API remains available for compatibility.
The backend repository remains the single source of truth. This project does not fork or edit the Gorape Docker environment; it adds Compose overrides and development scripts that layer on top of it.
- Keycloak login for Android, iOS and macOS via
flutter_appauth(public client, PKCE S256,openid profile, audiencegorape-api). - Keycloak login on Windows/Linux/Web via system-browser or browser redirect Authorization Code + PKCE with ID-token validation.
- Access-token-only Gorape API client. The ID token is never sent to Gorape. An expired access token triggers one refresh-and-retry instead of dropping the session.
- Project, device, registration, proof and attestation endpoints from
gorape/docs/openapi/openapi.yaml, including Gorape RP WebAuthn registration and assertion. - Group and role management endpoints (group CRUD, group devices, project / group role bindings) from the same contract.
- Role-aware UI driven by Keycloak token claims: cluster (realm) overview, per-project management and per-group management. Viewers get read-only screens; editors can register/revoke devices and assign group devices; admins can also create/edit/delete groups and grant project/group roles.
- Device registration and proof use the
passkeys2.23.2 Flutter plugin on Android, iOS, macOS, Windows and Web. Attestation presence/format is provider-dependent and is never inferred by the client. - Linux uses the gf-app WebAuthn ceremony page in Chrome/Firefox; Gorape exposes only one-time challenge APIs and does not serve an end-user UI.
- Explicit platform support matrix in the UI and live legacy-verifier capabilities.
- Legacy local-only policy preferences remain informational; WebAuthn attestation acceptance is controlled by the Gorape server config, never by client policy.
- Automated tests for API contracts, role claim resolution, settings, local policy, registration and proof orchestration.
- Flutter 3.38+/Dart 3.10+ (developed with Flutter 3.38.2 / Dart 3.10).
- Docker Desktop with Docker Compose v2.24 or newer (the overrides use
!reset/!override). - The Gorape backend checkout, by default as a sibling directory:
../gorape. - Android SDK plus a connected emulator or physical device for Android work.
- Xcode for iOS/macOS builds (not installed/validated in this environment).
cd gf-app
# 1. Download Google's Android Key Attestation roots and generate a server
# config that points at them. Files go to git-ignored config/generated/.
./scripts/generate-android-trust-config.sh
# 2. Generate a local HTTPS CA/server certificate (private keys are ignored).
./scripts/generate-local-tls.sh
# 3. Build/start postgres, redis, keycloak and the Gorape server from ../gorape.
./scripts/gorape-up.sh --https --android-attestation
# 4. A fresh local stack imports the Keycloak realm and seeds the demo project
# and permission fixtures from configuration files. No API bootstrap step.
# 5. Install config/generated/tls/ca.crt as an Android user CA once, then run.
# The script configures the debug Dart client and adb-reverses API/OIDC TLS.
./scripts/run-android.shDebug builds emit structured JSON diagnostics through dart:developer. On
Android, view them in Android Studio Logcat or with flutter logs; entries carry
a stable logger MCode such as FAPI002 or FPKY004. Release builds suppress
these logs by default. To opt in for a diagnostic release build:
flutter build apk --release \
--dart-define=GF_APP_LOG_ENABLED=true \
--dart-define=GF_APP_LOG_LEVEL=INFOGF_APP_LOG_LEVEL accepts DEBUG, INFO, WARN, ERROR or FATAL.
Structured JSON is on by default; GF_APP_LOG_STRUCTURED=false selects readable
text output. Authorization material, WebAuthn credentials/challenges/signatures,
request bodies and resource IDs are not logged; sensitive field names and
token-shaped strings are redacted as a defense in depth.
The default API endpoint is https://api.gorapeflutter.site:8443. To check it
outside the app, use the generated CA explicitly:
curl --cacert config/generated/tls/ca.crt https://api.gorapeflutter.site:8443/healthThe CA/server private keys are mode 0600 and live only in the Git-ignored
config/generated/tls/ directory. *.gorapeflutter.site resolves to
127.0.0.1 in local development, so the local certificate is valid for
api.gorapeflutter.site, idp.gorapeflutter.site and app.gorapeflutter.site.
This self-signed certificate is for local API/OIDC development only. Production
API and OIDC endpoints must use publicly trusted certificates.
Android Credential Manager and Apple Associated Domains use the RP ID
gorapeflutter.site (eTLD+1). The public association files are served from the
apex domain at https://gorapeflutter.site/.well-known/assetlinks.json and
https://gorapeflutter.site/.well-known/apple-app-site-association. The
Digital Asset Links statement includes both
delegate_permission/common.get_login_creds and
delegate_permission/common.handle_all_urls for package
com.gorapeflutter.gf_app. The API and IdP hostnames are separate from the RP
domain. See docs/en/DEVICE_TRUST_SPEC.md.
Keycloak redirects, passwordless WebAuthn, the passkey-only login flow, AMR
mapper, and test users/groups are declared in
../gorape/etc/keycloak/gorape-realm.json. Gorape's demo project and
role/group bindings are seeded by PostgreSQL's docker-entrypoint-initdb.d
files. Keycloak import and PostgreSQL initialization run only for a fresh local
database; recreating the tmpfs Postgres container also resets Keycloak users and
their passkeys, which must be registered again.
Check that the legacy Android Key Attestation verifier is active:
curl --cacert config/generated/tls/ca.crt https://api.gorapeflutter.site:8443/health
# {"service":"gorape","status":"ok"}
TOKEN=$(cat ../gorape/etc/.gorape/client/admin/access_token)
curl -s -H "Authorization: Bearer $TOKEN" \
--cacert config/generated/tls/ca.crt \
https://api.gorapeflutter.site:8443/v1/projects/805c5265-7315-420b-8aa7-3aea715ed88a/attestation/capabilities
# {"verifiers":{"android":"implemented","ios":"unsupported", ...}}The project ID above is available only in a database that was seeded with the
development data. A fresh Compose database requires the bootstrap step above;
then use an ID returned by GET /v1/projects.
--android-attestation configures only the legacy Android Keystore verifier; it
does not enable WebAuthn passkey attestation. Before passkey registration,
apply Gorape migrations 000003_webauthn and 000004_assurance, configure a
stable WebAuthn RP ID (gorapeflutter.site) and exact origins, explicitly allow
formats and mount their trust anchors. The default empty allowlist rejects
registration. Android also needs Digital Asset Links on the RP domain, and
iOS/macOS need AASA plus the webcredentials:gorapeflutter.site entitlement.
See setup.
The image is an override; the backend compose file is untouched.
# Floating latest (fine for experiments)
./scripts/gorape-up.sh --hub --android-attestation
# Recommended: pin a published tag or digest
GORAPE_SERVER_IMAGE=gorapeflutter/gorape:sha-7d9703b \
./scripts/gorape-up.sh --hub --pull --android-attestationAvailable tags are visible on Docker Hub (latest, main, sha-…). The
override sets image and removes the local build section with
build: !reset null.
Runtime defaults:
| Setting | Default | Notes |
|---|---|---|
| API base URL | https://api.gorapeflutter.site:8443 |
Local TLS listener; *.gorapeflutter.site resolves to 127.0.0.1, Android runner uses adb reverse and debug-only CA trust |
| OIDC issuer | https://idp.gorapeflutter.site:9443/realms/gorape |
Must exactly match Keycloak discovery and iss; install the local CA on Android |
| WebAuthn RP ID | gorapeflutter.site |
eTLD+1; association files at the apex /.well-known/ |
| Client ID | gorape-client |
Public client, PKCE only |
| Android/iOS/macOS redirect | com.gorapeflutter.gfapp:/oauth2redirect |
Registered on the Keycloak client |
| Windows/Linux redirect | http://127.0.0.1:8401/oauth2redirect |
System-browser loopback callback |
| Web redirect | Same-origin /auth.html |
Local dev default: https://app.gorapeflutter.site:5174/auth.html (or http://localhost:5000/auth.html) |
| Scopes | openid profile |
Audience gorape-api comes from a mapper |
Override at build/run time with --dart-define:
flutter run \
--dart-define=GORAPE_API_BASE_URL=https://api.example.com \
--dart-define=GORAPE_OIDC_ISSUER=https://keycloak.example.com/realms/gorape \
--dart-define=GORAPE_OIDC_CLIENT_ID=gorape-client \
--dart-define=GORAPE_OIDC_REDIRECT_URI=http://127.0.0.1:8401/oauth2redirectOverride the redirect URI per target deployment. The Keycloak public client must
allow each target's exact redirect URI; Web deployments must also add the Web
origin to webOrigins for discovery/token CORS.
Values can also be edited in the app under Settings. They are stored in the OS secure storage, not in the Gorape backend.
The app language can be changed under Settings → Display language. Japanese and English are supported; the selection is stored locally and defaults to Japanese.
The OIDC issuer must remain identical to the issuer that Keycloak puts in the token. Replacing only the host (for example using
10.0.2.2for the issuer) makes token validation fail. Useadb reverse tcp:8080 tcp:8080or a proper hostname with matching Keycloak hostname configuration instead.
Only endpoints present in the backend OpenAPI contract are used:
| Method | Path |
|---|---|
| GET | /health |
| GET | /v1/projects |
| GET | /v1/projects/{projectId} |
| GET | /v1/projects/{projectId}/devices |
| GET | /v1/projects/{projectId}/devices/{deviceId} |
| DELETE | /v1/projects/{projectId}/devices/{deviceId} |
| POST | /v1/projects/{projectId}/devices/registration/challenge |
| POST | /v1/projects/{projectId}/devices/registration/verify |
| POST | /v1/projects/{projectId}/devices/passkeys/registration/options |
| POST | /v1/projects/{projectId}/devices/passkeys/registration/verify |
| POST | /v1/projects/{projectId}/devices/{deviceId}/challenge |
| POST | /v1/projects/{projectId}/devices/{deviceId}/verify |
| POST | /v1/projects/{projectId}/devices/{deviceId}/passkeys/authentication/options |
| POST | /v1/projects/{projectId}/devices/{deviceId}/passkeys/authentication/verify |
| GET | /v1/projects/{projectId}/attestation/capabilities |
| GET | /v1/projects/{projectId}/devices/{deviceId}/attestation |
| GET/POST | /v1/projects/{projectId}/groups |
| GET/PATCH/DELETE | /v1/projects/{projectId}/groups/{groupId} |
| GET/POST | /v1/projects/{projectId}/groups/{groupId}/devices |
| DELETE | /v1/projects/{projectId}/groups/{groupId}/devices/{deviceId} |
| GET/POST | /v1/projects/{projectId}/roles |
| DELETE | /v1/projects/{projectId}/roles/{bindingId} |
| GET/POST | /v1/projects/{projectId}/groups/{groupId}/roles |
| DELETE | /v1/projects/{projectId}/groups/{groupId}/roles/{bindingId} |
Passkey registration and device proof use Gorape's separate WebAuthn RP endpoints. Keycloak passkeys remain Keycloak credentials and cannot be reused for Gorape because their RP IDs differ. The legacy Android Keystore endpoints remain available for compatibility; the device registration UI uses the WebAuthn flow.
The 管理 tab has three scopes: クラスタ (Keycloak realm), プロジェクト and グループ. Roles are resolved client-side from the access token for display and action gating. The backend is authoritative and combines Gorape project/group role bindings with configured Keycloak roles and group-path claims when authorizing requests.
Supported claim conventions (all optional):
| Claim | Meaning |
|---|---|
realm_access.roles / resource_access.*.roles |
admin, editor, viewer (the seeded app role maps to viewer; owner maps to admin) |
gorape_cluster_role |
Explicit realm-wide role |
gorape_project_role |
Project-wide fallback role |
gorape_project_roles |
JSON object keyed by project slug/id |
gorape_project_<slug>_role |
Per-project user attribute |
gorape_group_role |
Group-wide fallback role |
gorape_group_roles |
JSON object keyed by group slug/path |
gorape_group_<slug>_role |
Per-group user attribute (for example gorape_group_group001_role: ["owner"]) |
groups |
Group paths; /group004/editor also assigns a role |
The seeded realm (../gorape/etc/keycloak/gorape-realm.json) maps groups plus
every gorape_group_<slug>_role user attribute into the gorape-client access
token. Realms configured by hand need those mappers added to the client:
- Group Membership mapper → claim
groups, full path, access token. - One User Attribute mapper per group attribute → claim name equal to the attribute name, multivalued, access token.
Role changes take effect after the next token refresh or sign-in. Realm roles are
the quickest way to switch the whole UI: grant admin, editor or viewer
(realm roles editor and viewer are included in the seed realm).
Client/plugin and legacy-verifier capabilities:
| Platform | Keycloak login | Gorape passkey ceremony | Local OS key | Gorape verifier / assurance |
|---|---|---|---|---|
| Android | Yes | Yes | Yes (Keystore, Credential Manager/provider-dependent) | WebAuthn attestation verified by Gorape; android-key TEE/StrongBox can reach hardware_attested when BE=false |
| iOS | Yes | Yes (AuthenticationServices) | Yes (Secure Enclave) | apple anonymous attestation can reach hardware_attested when BE=false |
| macOS | Yes | Yes (AuthenticationServices) | Yes (Secure Enclave) | Same as iOS; physical validation unverified |
| Windows | Yes (system browser + PKCE) | Yes (Windows WebAuthn API) | Yes (CNG / Platform Crypto Provider, TPM-backed when available) | tpm attestation can reach hardware_attested; physical TPM statement unverified |
| Linux | Yes (system browser + PKCE) | Yes (gf-app browser ceremony page) | Yes (TPM2 via tpm2-tools) |
Legacy verifier unsupported; assurance depends on the browser authenticator |
| Web | Yes (browser redirect + PKCE) | Yes (browser WebAuthn API) | Not applicable | Browser-authenticator dependent; no independent client is required |
The passkeys Flutter plugin returns the full WebAuthn credential response on
Android, iOS, macOS, Windows, and Web, but an attestation: direct request is a
preference, not a guarantee. Providers may return none; Apple platform
credentials do not expose a conveyance preference through the plugin. Gorape
validates the actual fmt and trust chain and applies default-deny policy. The
resulting assurance level is derived only from verified evidence:
| Level | Condition |
|---|---|
hardware_attested |
verified attestation chain, hardware-protected non-exportable key, BE=false |
device_bound_unattested |
verified registration, BE=false, no hardware proof |
standard_passkey |
verified registration, BE=true (synchronizable) |
rejected |
verification failed, MDS status unacceptable, or revoked |
The server never promotes a credential from the client-supplied platform name.
A high-assurance deployment sets
attestation.webauthn.assurance.required: hardware_attested and
allow_synced_passkeys: false; Gorape validates that policy and a
hardware-capable format or FIDO MDS is configured at startup.
Linux's native passkeys plugin is unavailable, so the gf-app web asset performs the ceremony in Chrome/Firefox at the configured RP origin; Gorape remains API-only. Windows/Web use their native/browser WebAuthn APIs.
Before deploying, configure one stable Gorape RP ID (gorapeflutter.site) and
associate the app with that domain: Android Digital Asset Links, Apple
AASA/webcredentials entitlements, and an RP ID matching the Web origin. For
Linux browser handoff, set Application.Server.WebAuthn.portal_origin to the
gf-app web origin, browser_api_origin to Gorape's public API origin, and allow
the portal origin in Application.Server.web_origins for CORS. Add exact
WebAuthn origins to rp_origins. These platform associations are separate from
Keycloak's setup.
lib/
config/ Runtime configuration defaults
controller/ Riverpod controllers and dependency injection for the UI
entity/ Model, request, and response definitions
usecase/ Authentication, device registration, proof, and app workflows
repository/ HTTP, AppAuth, secure storage, MethodChannel, and platform adapters
share/ Shared exceptions and stateless transformations
ui/ Login, devices, registration, management, support, settings
android/ MainActivity.kt Keystore/attestation MethodChannel bridge
docker/ gf-app Compose overrides (backend files are not edited)
scripts/ Backend, Keycloak, trust-anchor and Android dev helpers
test/ Unit/widget tests
As in cmn-core, layers are split by concept (project.dart, device.dart,
attestation.dart, and so on). Repositories, use cases, and controllers keep
their public interfaces, implementations, and constructors together. UI
processing starts through controllers.
./scripts/check.sh # format check + dart analyze + flutter test
./scripts/check.sh --apk # additionally build the debug APKdart analyze is used instead of flutter analyze: in this SDK build
flutter analyze crashes because the analysis_server.dart.snapshot file is
missing while the AOT snapshot exists.
- Local development uses HTTP. Release builds must use HTTPS for the API and Keycloak, and a registered HTTPS or platform-native redirect URI.
- Only the access token is sent to Gorape. The ID token is kept for sign-out hints and never used as an API bearer token.
- Passkey private keys remain in the OS/browser credential provider. The app forwards the complete WebAuthn response; Gorape verifies before persisting the credential public key and removes the raw attestation evidence from the stored credential record.
- The legacy Android Keystore flow still keeps private keys in Keystore and sends its public key/certificate chain to Gorape.
config/generated/is git-ignored because it contains machine-specific absolute paths and downloaded trust anchors.- The bundled Keycloak admin credentials (
admin/admin) and seeded user passwords are development-only. Never reuse them outside local development.
- Real passkey attestation is provider-dependent. Android may return
android-keyornone; Windows may or may not return TPM attestation; Apple may return an anonymousapplestatement ornone; browsers can anonymize. Default policy rejectsnone, unconfigured formats, and untrusted chains.standard_passkey/device_bound_unattestedremain valid outcomes; only verified hardware evidence yieldshardware_attested. - The apex
gorapeflutter.sitecurrently has no public A/AAAA record (only NS/SOA). Public DAL/AASA retrieval athttps://gorapeflutter.site/.well-known/...and public TLS issuance are therefore unverified until DNS and certificates are provisioned. The wildcard*.gorapeflutter.site -> 127.0.0.1records used for local development are not a public deployment. - Android release signing key and Apple production Team ID/provisioning are not available in this environment; DAL contains debug fingerprints only and AASA production publication is unverified.
- Physical-device verification of Android Credential Manager
fmt=none, Apple anonymous attestation, and Windows TPM attestation is unverified in this environment. - iOS/macOS builds could not be validated here because Xcode is incomplete.
- Linux browser handoff requires Gorape's RP ceremony page and a matching
portal_origin; Windows/Web use the platform/browser WebAuthn APIs. - The backend has no policy API; the policy screen is explicitly local-only.
- Gorape has no cluster-wide or "my role" API. The クラスタ screen is built from Keycloak claims and the projects visible to the signed-in user; per-project and per-group role bindings are only listed for callers the backend already allows.
- Swagger UI/godoc are optional containers (
make docsin the backend).
- The mdBook documentation is published as separate English and Japanese books
at
https://gorapeflutter.github.io/gf-app/en/andhttps://gorapeflutter.github.io/gf-app/jp/, each with an independent table of contents. The root URL is a language chooser. Install the tools and build both books:Opencargo install mdbook cargo install mdbook-mermaid scripts/docs/build-book.sh
build/docs-site/index.htmlto choose a language, or open theen/andjp/subdirectories directly. - Before the first deployment, a repository administrator must enable Pages in
Settings → Pages → Build and deployment → Source → GitHub Actions. GitHub
does not allow the workflow's
GITHUB_TOKENto create the Pages site. After this one-time setup, the workflow builds on pull requests and deploys pushes tomainathttps://gorapeflutter.github.io/gf-app/. scripts/docs/link_gf_ids.pylinks documentation IDs to their source-comment line on GitHub. It skips fenced diagrams; run it after moving ID comments.- English chapter sources:
docs/en/ - 日本語章のソース:
docs/jp/
