Ace ID Deployment and Operations

This runbook applies to the Node.js / Express / OpenID Connect service in aceyash-dev/ace-id, deployed on Deplexo. The Flutter Android app lives in the separate aceyash-dev/AceID repository. The web frontend is configured as a separate Vercel project; Vercel is not the production host for this OIDC backend.

Required configuration

• ISSUER: canonical HTTPS issuer URL. Keep it stable; clients validate it exactly.
• DATABASE_URL: PostgreSQL connection string from the secret manager.
• SESSION_SECRET: high-entropy secret shared by instances that must validate the same sessions.
• JWKS_JSON: current OIDC signing keys. Never commit private key material.
• ACEID_MOBILE_CLIENT_ID: the exact registered public OIDC client ID permitted to use bearer tokens with account-management APIs. Keep this aligned with the public client configured in the Android repository. If unset, bearer-token account API authentication fails closed; browser cookie sessions are unaffected.
• AUDIT_IP_HASH_KEY: recommended independent high-entropy secret for keyed IP pseudonyms. If omitted, Ace ID falls back to SESSION_SECRET; rotation of that fallback changes pseudonyms.

Keep secrets out of logs, source control, client bundles and mobile packages.

CI and deployment isolation

Backend CI runs in aceyash-dev/ace-id for backend changes and validates the Node.js syntax, UI checks, security tests, OIDC contract, and configured live issuer smoke test. Android CI and APK artifacts live in aceyash-dev/AceID and are independent of the backend deployment.

Deploy the OIDC backend through Deplexo. The Vercel project is for the frontend and must not be treated as the backend deployment or used to change the backend issuer configuration.

Pre-deployment checklist

1. Verify ISSUER, database connectivity and signing-key configuration in the target environment.
2. Run npm ci, npm run check, npm run check_ui and npm run check_security.
3. Verify OIDC discovery, authorization-code + PKCE login, callback, token exchange, logout, revocation, MFA and recovery.
4. Confirm rate limits are shared across application instances and behave correctly during database failure.
5. Verify secure cookies, trusted proxy configuration, no-store headers and redacted structured logs.
6. Confirm database backups and a tested rollback plan before schema changes.
7. Check readiness and latency metrics after rollout; a successful build is not proof of a healthy production flow.

Database and performance

• Tune DATABASE_POOL_MAX to the database connection budget across all running instances.
• Use npm run benchmark:db against staging with representative concurrency. It is a baseline, not a load test.
• Keep schema changes in reviewed, versioned migrations. Do not use startup code for unbounded or destructive cleanup.
• Alert on elevated authorization failures, rate-limit backend failures, database pool saturation and rising p95/p99 latency.

Origin and proxy behavior

The browser Origin check is a CSRF defense, not authorization. Do not trust arbitrary Host headers or wildcard origins. Configure TRUST_PROXY_HOPS to match the actual trusted proxy chain; do not use a permissive value when the app can be reached directly.

Mobile client boundary

The mobile app must use the existing Ace ID issuer with Authorization Code + PKCE and the registered redirect URI app.tab.aid:/oauth2redirect. Never embed a client secret, database credential, session secret or signing key in an APK/IPA. Account-management APIs accept bearer tokens only when the token belongs to the exact ACEID_MOBILE_CLIENT_ID configured on the backend, has a valid expiry, and is bound to an account. Third-party OIDC client tokens must not inherit account-management privileges. Browser cookie-session authentication remains unchanged.