hrynco-notification-service/docs/android-push.md

# Push channels and Android FCM — IT-1074

Notification Service owns Firebase configuration. Invemory owns installation/user bindings
and notification preferences; it publishes a push request without Firebase credentials or OAuth access tokens.
The public Contracts package must be delivered first; updating Invemory is a separate step.

## Administration

The **Push Channels** menu opens /admin/push-channels. Create/Edit use the existing service
catalog (ServiceId UUID), Firebase Project ID, service account JSON and Active. Fields use
compact desktop widths and wrap on small screens. A service has one push channel, enforced
by a unique ServiceId index. There is no priority/fallback or extra routing configuration.
Inactive channels are retained but never selected for sending. Reassignment is allowed;
service rename automatically updates the displayed name without breaking the FK.

Creating a channel requires a valid service-account JSON whose project_id matches the
Firebase Project ID. The server validates its type, email and RSA private key without
contacting Google. Editing with an empty credentials field preserves the stored value;
changing the project requires replacement credentials. An inactive channel also requires
valid credentials, so activation does not introduce a partly configured channel.

Safe list/edit models contain no secret. Edit does not load credentials into the browser,
and validation failures clear both the model and attempted ModelState value before rendering.
Credential parser/provider errors use fixed messages and never log the JSON/private key.
The Worker constructs Google credentials from the validated service-account email/private
key; supplied token_uri or other endpoint fields are not used. There is no ADC fallback.

Storage follows the existing SMTP approach: credentials are server-only JSONB in the
Notification Service database, without new application-level encryption. Restrict access
to this private administration app, its database and backups. Existing private-network
access assumptions are unchanged; this feature adds no public administration endpoint.

## Persistence and migration

Apply 20261024080457_AddPushChannels before opening Push Channels or enabling delivery.
The additive migration creates push_channels with a required services.id FK using RESTRICT
and unique service_id index. It does not alter existing email channels, settings or usage.
Service deletion is blocked while either email or push channels still reference it; reassign
a push channel before deleting its service. Saves reuse the service administration transaction
lock to serialize service membership and duplicate-channel checks. Migration downgrade drops
push channels and their credentials, so it is destructive after channels have been configured.

The existing DAL.EF/update-development-database.bat applies the schema to the database from
the Web Development configuration; it does not provision containers or restart Web/Worker.

## Worker and contracts

Set FcmPush__Enabled=true to register the push consumer. Firebase project/credentials and
service routing come from the active channel, not environment settings or producer payloads.
The previous draft FcmPush__ServiceName host filter is removed: each request's exact current
ServiceName resolves to services.id and then that service's active push channel. Missing
services, missing/inactive channels and invalid stored configuration produce safe terminal
failure results without contacting Firebase. No legacy service-name alias is used at runtime.

SendPushMessageData retains registration/binding/user identity, ServiceName, device Token
and TokenHash, title/body, version, /home route and ExpiresAt. FcmProjectId, FcmAccessToken and
FcmAccessTokenExpiresAt have been removed. SupportedMessageType remains public in Contracts;
the existing Notification.SendPush.v1 header and notification.send-push queue are unchanged.
OAuth tokens are obtained by the Firebase SDK inside Notification Service from the channel's
service account. They are never included in RabbitMQ request/result contracts.

This replaces the unpublished draft that obtained OAuth authorization in Invemory. Source
clients still initializing the removed properties must update after the new Contracts package
is explicitly published. Old payloads containing additional JSON fields are not a configuration
source; the server ignores those fields and still requires its own active channel. Do not
resume producers that send Firebase secrets until that separate Invemory update removes them.
No Invemory source or production configuration is changed by this task.

The Worker sends bounded version-1 data-only messages with /home routes and a maximum
15-minute expiry, preserving Android binding checks before display. Delivery outcomes are
persisted by service/message ID under an advisory lock and replayed after reply failures.
A crash after FCM acceptance but before DB commit may still repeat delivery; this is not
exactly-once delivery. Expired messages are not sent.

UNREGISTERED invalidates only the matching registration/binding/token-hash. Sender mismatch,
invalid argument and authorization/configuration failures do not invalidate device tokens.
Transient delivery uses the existing three attempts, exponential delay, jitter and Retry-After.
Outcomes expire after 30 days; existing outcome/retry metrics contain no target/token labels.
Firebase acceptance does not guarantee Android display (force-stop, Doze and connectivity apply).

## Validation boundaries

Tests cover the administration lifecycle, secret non-disclosure, unchanged-secret edits,
service reassignment/rename, inactive selection, duplicate/missing services, project changes,
worker name-to-ID resolution, server credential selection and credential-free Contracts.
All provider routing tests use a fake Firebase client. Real Firebase delivery, credential
permissions and Android notification display require a separate end-to-end verification
with an authorized configured project/device; fake local credentials cannot prove those.

On 2026-10-24 the Release solution build and targeted tests passed (21 unit and
24 integration). Rider inspection reported no errors in the changed production classes;
the existing Firebase SDK Token deprecation warning remains. Structural review kept
changed methods within cognitive complexity 10; the tool did not report numeric scores.
The review compared email-channel mapping/editor patterns, service catalog controllers,
transaction locking and existing push delivery/retry behavior. No unresolved blocking
findings remained for the implemented scope.

Desktop browser validation used a disposable database and Web at 127.0.0.1:52658, with
an offline-generated test service account (no Google account or network send): empty
list, create, invalid JSON feedback/secret clearing, edit without secret disclosure, and
Active off with credentials preserved all passed. Mobile wrapping was inspected in CSS
but not exercised on an Android device. The temporary Web and database container were
removed after validation. The owner-applied AddPushChannels migration was separately
confirmed in the existing development database; it was not reapplied.

## Channel tests — 2026-10-24

The editor has separate **Check Firebase authorization** and **Send test push** actions,
following the current-form SMTP test workflow. Neither action saves a channel. New channels
use the entered service-account JSON; blank JSON on an existing channel uses its stored
credentials only if the project is unchanged. Inactive channels can be tested explicitly.
Both POST endpoints require the form antiforgery token and bounded request bodies.
The existing private-network/port-forward access boundary is retained: this Web application
has no in-app authentication or administrator-role middleware. Do not expose it publicly.

Authorization requests an OAuth access token with the firebase.messaging scope and a
30-second timeout. It neither requires a recipient nor calls FCM send. A successful OAuth
exchange proves service-account authentication only, not FCM API enablement, send permission
or device delivery. The access token is never returned, saved or logged.

Send opens a separate Recipient token field and sends a neutral notification message through
the same FirebasePushClient transport using current form credentials. RecipientToken is not
part of the save model or channel storage. The dialog clears it after the attempt or close.
Only test on an explicitly supplied, owned test-device token. Provider acceptance is shown
as acceptance, never as verified delivery/display. This direct provider diagnostic does not
exercise Invemory's data-only binding, expiry/tap checks, transactional Outbox or result queue;
it does not replace that separate end-to-end validation. Foreground display depends on the
receiving app. No user inventory or account data is included.

Errors are fixed, safe messages; no provider exception, credentials, access token or recipient
is echoed. The UI uses textContent for results. Saved credentials never populate the editor.

### Channel-test verification

Release solution build passed. 29 focused push unit tests and 9 PushChannelAdmin integration
tests passed, including CSRF rejection, missing credentials, unchanged/changed project reuse,
unsaved credentials, separate authorization/send calls, transient errors and no persistence.
Rider's final changed-file error inspection was clean. Existing FirebaseAdmin Message.Token
obsolescence and Microsoft.OpenApi vulnerability warnings remain outside this task.
Cognitive complexity was manually reviewed, not numerically measured.

A temporary local Web instance on 127.0.0.1:52658 verified both buttons, modal recipient input,
empty-token validation, missing-credential response and clearing the recipient after a failed
attempt. Only a fake non-deliverable token with missing credentials was submitted; the
request stopped before Firebase. No channel was created or modified by this UI verification.
Code review compared current SMTP test behavior, existing credential parser/provider,
Razor editor layout, antiforgery and repository interfaces. Fixed script initialization to
wait until footer buttons exist and rejected malformed/oversized test requests safely.
The final review found no further actionable issue in these two actions.

The owner subsequently configured the local channel, verified OAuth authorization and sent
a real test to the current Samsung token on 2026-10-24. The owner confirmed notification
display and opening the installed application on tap. This validates the direct Firebase
notification test, not the Invemory data-only/outbox flow. The installed receiver intentionally
validates data-only binding fields; a notification-only test received while Invemory is in
the foreground does not satisfy that contract. Background notification display is handled
by the Firebase SDK. No additional diagnostic messages were sent by the agent.

The authorization button and its result are directly beneath the service-account JSON
field. The recipient input and Send test push button remain in the separate test dialog.

Delivery verification: the full Release solution build and all 221 tests passed (67 unit,
154 integration). The pre-existing Microsoft.OpenApi 2.0.0 vulnerability warning remains.
Delivery is restricted to Notification Service; Invemory producer/client migration and its
runtime validation remain separate pending work. TeamCity main triggers include general
checks, image publication, Contracts publication and production deployment. The owner
explicitly authorized this automatic production consequence for the Notification Service
delivery on 2026-10-24. It does not authorize delivery of the remaining Invemory repositories.