@lunch-money/developer-docs 2.11.2 → 2.11.3-preview.1

package/docs/oauth/native-apps.md

@@ -0,0 +1,89 @@
+# OAuth for native iOS and Android apps
+
+Native apps are public clients: they cannot keep a client secret. Use authorization code with PKCE and launch Lunch Money sign-in and consent in a trusted platform authentication browser—not an embedded WebView.
+
+Lunch Money requires PKCE with the `S256` challenge method for every client, public or confidential. Native clients send no client secret.
+
+## Recommended libraries
+
+- iOS and macOS: [`AppAuth-iOS`](https://github.com/openid/AppAuth-iOS), presented through `ASWebAuthenticationSession`.
+- Android: [`AppAuth-Android`](https://github.com/openid/AppAuth-Android), which uses a browser Custom Tab.
+- Bare or non-Expo React Native: [`react-native-app-auth`](https://github.com/FormidableLabs/react-native-app-auth).
+- Expo: Use [`expo-auth-session`](https://docs.expo.dev/versions/latest/sdk/auth-session/) for browser-based OAuth flows.
+
+Use Lunch Money's authorization-server discovery document and configure `token_endpoint_auth_method=none`. Send the client ID at the token and revocation endpoints, but never invent or embed a client secret. You do not need to configure authorization-request scopes because the registered client receives its complete fixed set. If your OAuth library sends `scope`, Lunch Money ignores that value and uses the registered set.
+
+## Redirects
+
+Use a redirect mechanism that returns control to your app and that your platform can bind to it. Claimed HTTPS redirects or Android App Links provide stronger app ownership than a custom URI scheme when correctly configured. A private-use scheme must contain a dot, such as `app.example.demo:/oauth/callback`, and must be protected against interception.
+
+Lunch Money accepts a well-formed non-loopback HTTPS redirect URI but does not fetch or validate an Apple `apple-app-site-association` file or Android `assetlinks.json` file. Platform association remains your responsibility:
+
+- For AppAuth-iOS HTTPS redirects, use iOS 17.4 or later, add an Associated Domains entitlement for the redirect host with the `webcredentials` service, and publish an `apple-app-site-association` file that lists the app under `webcredentials`. An `applinks` association by itself is not sufficient for AppAuth-iOS.
+- For Android App Links, add an HTTPS intent filter with `android:autoVerify="true"` for the redirect host and publish `https://HOST/.well-known/assetlinks.json` with the app package name and signing-certificate fingerprint.
+
+Test the installed application with the production-signed association before release. Successful client registration proves only that the redirect URI is syntactically eligible; it does not prove that the operating system will return the authorization response to your app.
+
+Native clients may use an HTTP loopback redirect with `localhost`, `127.0.0.1`, or `[::1]`. The scheme, host, path, and query string must exactly match the registered URI, but the port may differ so the application can bind an ephemeral port at runtime. The exception applies only to loopback redirects for native clients; native HTTPS and private-use scheme redirects must match every component of the registered URI exactly. The loopback hosts are not interchangeable: a client registered with `http://127.0.0.1/cb` cannot authorize with `http://localhost:4000/cb` or `http://[::1]:4000/cb`, so register the host your app actually binds to.
+
+## Store and renew tokens
+
+Store tokens in Keychain on Apple platforms. If an app and its extensions both refresh, place the complete credential set in a Keychain access group they can share. On Android, use current Keystore-backed storage guidance from your maintained library; do not start new work with deprecated `EncryptedSharedPreferences` APIs.
+
+Serialize refreshes with a cross-process lock for each connection. After acquiring the lock, re-read the stored credential set because another process may already have refreshed it. Persist the complete replacement set before using the new access token or releasing the lock. If a successful refresh response is lost before it is saved, do not retry with the consumed refresh token: replay revokes the token family, so the user must authorize again.
+
+After every code exchange, call and strictly validate `GET /v2/me` before adding the credentials to the app's normal connection store. For an app without its own user accounts, identify each local connection by the returned Lunch Money user `id` and budget-account `account_id` pair. Atomically create a record for a new pair or replace the credential set for an existing pair. Two Lunch Money users may authorize the same shared `account_id`; their credentials must remain in separate records. If identification or persistence fails, discard the temporary credentials instead of saving a partial or unidentified connection. Retain `budget_name` for display, but never use it as a key because different budget accounts can share a name.
+
+The platform authentication browser may reuse an existing Lunch Money login, and Lunch Money may let the person use a different user from the authorization screen. An ephemeral-session request is only an intent to avoid shared browser state; it does not prove which user completed authorization. Do not infer identity from browser cookies, callback fields, budget account names, or token contents. The validated `/v2/me` response is authoritative.
+
+Show the active Lunch Money identity when the app may retain more than one, show which authorized budget account is active, and provide one separate **Authorize another budget account** action that starts OAuth. Do not require another client-side action for switching Lunch Money users. Selecting an existing connection must not start authorization again, and the app must allow selection only among saved budget accounts for the active Lunch Money user.
+
+All API calls, refreshes, revocations, local deletions, and cached data must apply to the active user/account connection. Clear or partition profile, configuration, and cached financial data when the identity or budget account changes. When the active connection is removed, choose a deterministic remaining connection for that Lunch Money user or enter a disconnected state; never expose another user's hidden connection as a fallback. Use a secondary label such as the account ID only when duplicate visible budget account names need disambiguation.
+
+The app may retain credentials for inactive Lunch Money users in secure storage. Switching users hides the previous identity's connections without revoking or deleting them, and authorizing as that identity later may restore its saved budget accounts. Alternatively, an app may delete credentials during its own sign-out or user-switch lifecycle. Make the chosen behavior understandable without prescribing a particular native control.
+
+Present remote disconnect or revocation separately from forgetting a credential only on the device. Confirm local-only deletion and explain that it leaves the remote authorization active.
+
+### Keep application users' connections separate
+
+A native app can support multiple application users on the same device. If your app has its own sign-in system, keep each user's saved Lunch Money connections in a separate storage namespace. Bind the authorization attempt to the application user who started it, and retain the Lunch Money `id` and `account_id` returned by `GET /v2/me` with each credential set. Only load a connection after verifying that it belongs to the currently authenticated application user. Secure device storage does not perform that application-level ownership check for you.
+
+On application sign-out or application-user switching, stop work using the previous application user's credentials and clear in-memory tokens, the active connection selection, and cached financial data. Remove saved credentials if your app does not retain connections across sign-ins; otherwise, make them available only after their application owner signs in again. Do not attach an OAuth callback or refresh result from the previous session to the newly signed-in application user.
+
+If your app has no separate user accounts, the device's OS account and app storage protections provide the local access boundary. Anyone allowed to use the unlocked app may be able to use its saved connections; separate budget-account records alone do not authenticate different people.
+
+Sending tokens to an application backend introduces server-side credential storage. If your architecture does that, apply the [credential ownership rules](/oauth/security#associate-credentials-with-your-application-user) on the backend as well as protecting credentials on the device.
+
+Platform code should delegate protocol validation to the maintained library while your application supplies safe configuration, lifecycle storage, API calls, revocation, and user-facing recovery.
+
+## AppAuth-iOS outline
+
+Use AppAuth-iOS to discover Lunch Money's authorization-server metadata from `https://api.lunchmoney.dev`, then create an `OIDAuthorizationRequest` with the discovered configuration, your client ID, no client secret, the registered redirect URI, and the authorization-code response type. AppAuth-iOS presents the request with `ASWebAuthenticationSession`, generates an `S256` PKCE challenge, handles the callback, and exchanges the code when you use its authorization-state convenience flow.
+
+The following outline is illustrative; adapt ownership, error handling, and persistence to your application:
+
+```swift
+let issuer = URL(string: "https://api.lunchmoney.dev")!
+
+OIDAuthorizationService.discoverConfiguration(forIssuer: issuer) { configuration, error in
+    guard let configuration else { return handle(error) }
+    let request = OIDAuthorizationRequest(
+        configuration: configuration,
+        clientId: clientID,
+        clientSecret: nil,
+        scopes: nil,
+        redirectURL: redirectURL,
+        responseType: OIDResponseTypeCode,
+        additionalParameters: nil
+    )
+    authorizationFlow = OIDAuthState.authState(byPresenting: request, presenting: viewController) { state, error in
+        // Temporarily hold state, then validate GET /v2/me before saving it.
+    }
+}
+```
+
+After exchange, call `GET /v2/me` with the access token and strictly validate the Lunch Money user and budget-account identity before saving the credential set. For refresh, acquire the connection's cross-process lock, re-read the Keychain access-group record, ask `OIDAuthState` for a fresh access token only if the stored state still needs refresh, save the complete replacement state, and then make the API request. Treat a terminal refresh failure as a request for interactive authorization.
+
+This is integration guidance, not a complete Swift sample. The upstream AppAuth-iOS project remains the source for current library APIs and platform setup. Expo developers can use the [native Expo sample](/oauth/sample-applications#native-expo-sample) for a complete Lunch Money walkthrough and reference implementation.
+
+Next: [Review OAuth security guidance](/oauth/security).

package/docs/oauth/oauth-scope-catalog-design.md

@@ -0,0 +1,370 @@
+# OAuth scope catalog design proposal
+
+Status: first-cut ENG-616 implementation and inventory, pending consumer review.
+
+This document proposes a published, shared source of truth for OAuth scope
+definitions and scope-group presets published with the canonical V2 OpenAPI
+specification. It must still be reconciled with the server OAuth management API
+and database implementation before the catalog is finalized.
+
+## Context and decisions
+
+The catalog is application code, not persistence. OAuth clients, grants, and
+tokens store scope-name strings. Server, Developer Portal, and authorization UI
+reconcile those strings with their installed catalog version.
+
+The detailed OAuth technical specification currently contains an exploratory
+read/write scope list and says write implies read. Those points are superseded
+for this proposal: the final inventory will use independent `:read`, `:create`,
+`:update`, and `:delete` authorities where CRUD applies, and no authority implies
+another. Presets express common combinations without changing authorization
+semantics. Names such as `resource:read` in this document are generic examples,
+not production decisions.
+
+This proposal makes these additional decisions:
+
+- Keep `OAuthScopeCategory` as `identity | offline | api`. The category
+  distinguishes protocol scopes from API permissions. The published inventory
+  includes `offline_access` for requesting continued access through refresh
+  tokens, but does not publish OpenID Connect identity scopes (`openid`,
+  `email`, or `profile`).
+- Add optional `lifecycleNotice` copy for deprecation and retirement warnings.
+  It is display metadata, not runtime authorization policy.
+- Reject groups with identical member sets. This is simpler than display
+  priorities and makes exact matching unambiguous.
+- Allow unmapped public operations during rollout, but require callers to make
+  the choice explicit through an option such as
+  `operationIdCoverage: 'allow-unmapped'`. Validation should switch to
+  `require-all-mapped` before OAuth scope enforcement is declared complete.
+- Do not encode scope implication, expansion, grant rules, client approval,
+  refresh-token policy, or consent policy in the catalog.
+- Use catalog `operationIds` as the authority for V2 endpoint permissions.
+  Server decorators must be generated from or validated against this mapping so
+  they cannot become a second source of truth.
+- Scope V1 of this catalog to the V2 API only.
+- Map non-CRUD mutations by effect: Plaid and synced-crypto refresh operations
+  use `:update`; transaction split/group and their reversals use
+  `transactions:update`; balance-history and budget upserts use `:update`.
+- Keep attachment metadata and download access behind
+  `transaction_attachments:read`. The other `transaction_attachments:*` scopes
+  separately authorize attaching or deleting files.
+
+## Package direction
+
+The catalog ships as a browser-safe subpath of the existing
+`@lunch-money/v2-api-spec` package so the catalog and V2 `operationId` values are
+versioned atomically:
+
+```text
+src/oauth-scopes/            authored TypeScript catalog and helpers
+oauth-scopes/                compiled published subpath
+test/oauth-scopes/           catalog and V2 operationId validation
+```
+
+The runtime entry point has no Node-only dependencies and performs no filesystem
+or YAML work. OpenAPI parsing remains in build/test tooling and is not exported
+from the browser-safe `@lunch-money/v2-api-spec/oauth-scopes` subpath.
+
+## Public contract
+
+```ts
+type OAuthScopeName = string
+type OAuthScopeCategory = 'identity' | 'offline' | 'api'
+type OAuthScopeLifecycle = 'active' | 'deprecated' | 'retired'
+type KnownOAuthScopeName = 'me:read' | /* ... */ 'budgets:delete'
+
+interface OAuthScopeDefinition {
+  readonly name: KnownOAuthScopeName
+  readonly description: string
+  readonly category: OAuthScopeCategory
+  readonly operationIds: readonly string[]
+  readonly status: OAuthScopeLifecycle
+  readonly lifecycleNotice?: string
+}
+
+interface OAuthScopeGroupDefinition {
+  readonly id: string
+  readonly name: string
+  readonly description: string
+  readonly scopes: readonly KnownOAuthScopeName[]
+}
+
+interface OAuthCatalogDefinition {
+  readonly scopes: readonly OAuthScopeDefinition[]
+  readonly groups: readonly OAuthScopeGroupDefinition[]
+}
+```
+
+The `oauth-scopes` subpath exports:
+
+- The interfaces and aliases above, plus result and issue types.
+- `validateOAuthCatalog(definition, options)` returns all structured issues.
+- `getOAuthScopeDefinition(name)` returns a definition or `undefined`.
+- `getOAuthScopeForOperationId(operationId)` returns the authoritative scope
+  definition for a V2 operation or `undefined`.
+- `getOAuthScopeGroup(id)` returns a group or `undefined`.
+- `matchOAuthScopeGroup(names)` returns a discriminated matched/no-match
+  result.
+- Immutable `oauthCatalog`, `oauthScopes`, and `oauthScopeGroups` exports.
+
+`OAuthScopeName` remains `string` for persisted and API-facing input so consumers
+can preserve names newer than their installed library. `KnownOAuthScopeName`
+provides autocomplete and compile-time checking for this catalog version.
+
+## Runtime validation and immutability
+
+The published definitions and nested arrays are frozen. Private lookup maps
+support explicit failed lookups, and `validateOAuthCatalog` returns structured
+issues for build/test tooling without importing Node-only code into the runtime.
+
+Validation checks:
+
+- stable lowercase colon-delimited scope names and lowercase underscore group IDs;
+- required descriptions and valid category/lifecycle values;
+- unique scope names and group IDs;
+- non-empty API `operationIds`, except retired tombstones;
+- no operation IDs on identity or offline scopes;
+- duplicate operation IDs within a scope;
+- conflicting operation ownership unless an ID is deliberately allowlisted;
+- non-empty groups with unique members;
+- group members exist and are not retired;
+- offline scopes are excluded from groups;
+- duplicate group member sets are rejected.
+
+The runtime has no mutable singleton. Consumers import the frozen catalog or
+construct catalog fixtures in tests. Public helpers return
+`undefined` or discriminated results rather than using non-null assertions.
+
+## Protocol scopes
+
+`OAuthScopeCategory` includes `identity` and `offline` so validation can
+distinguish protocol scopes from API permissions. The published catalog ships
+`offline_access` alongside its API scopes.
+
+Lunch Money's authorization server exposes OAuth 2.1 authorization-server
+metadata, API scopes, and the `offline_access` protocol scope:
+
+- no `openid`, `email`, or `profile` identity scopes;
+- active `offline_access` with no V2 operation IDs;
+- no ID tokens, UserInfo, or public signing keys.
+
+`offline_access` represents a request for continued access when the user is not
+actively using the app. The authorization server still owns the decision to
+issue a refresh token based on the requested scope, client capability, consent,
+and server policy.
+
+No resource group may contain an offline-category scope. Identity scopes are
+not categorically banned from a group; any future identity-oriented preset
+should be an explicit catalog decision.
+
+## Lifecycle and consumer behavior
+
+Lifecycle is code-only metadata:
+
+| Status | New assignment/request | Existing full replacement | Token issuance | Recognition/display |
+| --- | --- | --- | --- | --- |
+| `active` | allowed | allowed | allowed | yes |
+| `deprecated` | rejected if newly introduced | preserved if already assigned | allowed for existing grants per server rollout | yes, with warning |
+| `retired` | rejected | rejected | rejected | yes, as tombstone |
+
+The library provides state and copy; consumers enforce transitions in context.
+For example, only the server can know whether a deprecated name is newly added
+or preserved during a full replacement. Lifecycle must never be copied into a
+client row. A stored name absent from the installed catalog is `unknown`, not
+implicitly retired.
+
+Recommended reconciliation status for management APIs:
+
+```ts
+type ScopeConfigurationStatus = 'valid' | 'needs_attention'
+```
+
+`needs_attention` applies when stored configuration contains an unknown or
+retired scope. A deprecated-only configuration remains valid but returns warning
+metadata. The exact API response shape is a server-design coordination point.
+
+## Compatibility baseline and change classes
+
+After the first production catalog is approved, check in a canonical JSON
+snapshot at `compatibility/catalog-baseline.json`. Future CI compares source
+against this file and does not fetch npm. The baseline updates only as part of a
+reviewed release and must represent the most recently published authority map.
+Canonical ordering makes diffs stable.
+
+Compatibility checks detect deletion, category changes/name reuse, authority
+broadening, operation remapping, lifecycle changes, and group membership/removal.
+The regular catalog validator separately detects broken references and duplicate
+ownership.
+
+Change classification:
+
+- Patch-compatible: descriptions, names shown to users, and lifecycle notice
+  copy change without changing authority.
+- Minor-compatible: a new scope or group is added. New scopes must not be added
+  to an existing group in the same classification; that is a membership change.
+- Migration-requiring: deprecation, retirement, removal of authority from a
+  scope, any group membership change, or group removal.
+- Breaking/forbidden without explicit migration: deleting a known scope rather
+  than retaining a tombstone, changing its category, reusing its name for a
+  different authority, or adding operation IDs to an existing scope.
+
+Name reuse cannot be detected from names alone. Preserving every old definition
+as a retired tombstone plus comparing category and operation ownership provides
+the deterministic safeguard. Review policy must treat meaning changes not
+visible in structured data as forbidden. A future `authorityFingerprint` could
+make that stronger if V1 endpoints or non-operation authorities join the model.
+
+A future comparison helper should treat a retired tombstone with removed
+operation IDs as migration-requiring rather than breaking. Tombstones should
+remain small while retaining enough description to diagnose old persisted names.
+
+## Exact-set group matching
+
+Groups are UI presets only. A selected group becomes its concrete member names;
+the group ID is neither sent as authority nor persisted in client, grant, code,
+or token configuration.
+
+Matching performs these steps:
+
+1. Reject a candidate containing an unknown or duplicate scope name with a
+   distinct no-match reason.
+2. Canonically sort the complete candidate set.
+3. Compare it with each complete canonical group member set.
+4. Return exactly one matched group or `no_match`.
+
+An additional recognized scope prevents a match. The helper never searches for
+subsets, decomposes a set into overlapping groups, or infers historical preset
+selection. A changed preset causes old clients to fall back to individual scope
+display. Duplicate member sets are invalid, so ambiguity cannot enter a valid
+catalog.
+
+Product analytics may separately record that a preset was selected, but that
+event is historical telemetry and has no authorization meaning.
+
+## OpenAPI operationId validation
+
+The V2 YAML is authoritative for public operation IDs. Node-only test tooling
+parses `v2/spec/lunch-money-api-v2.yaml`, traverses HTTP operations, and returns a set
+while rejecting missing or duplicate IDs. Catalog validation then:
+
+- verifies every API-category operation ID exists in the spec;
+- rejects conflicting ownership unless a deliberate `sharedOperationIds`
+  allowlist contains the ID;
+- permits identity/offline scopes to have no operation IDs;
+- reports stale and unknown IDs with catalog paths;
+- optionally reports every unmapped public operation.
+
+The validation modes are:
+
+- `allow-unmapped`: rollout mode; catalog entries must be correct, but endpoints
+  can remain unmapped while enforcement is staged.
+- `require-all-mapped`: completion mode; every public operation must have an
+  owner or be removed from the public spec.
+
+If some public operations are intentionally unscoped (for example a protocol or
+health endpoint represented in the same document), add a named exclusion list
+with a justification per entry rather than silently omitting them. Shared
+operation ownership should likewise be rare and explicit. The tooling never
+modifies the OpenAPI document.
+
+V1 endpoints are deliberately outside this catalog. Do not overload V2
+operation IDs with invented V1 values.
+
+## Consumer integration
+
+### Server
+
+- Pin an exact catalog package version in deploys.
+- Persist only scope-name strings.
+- Validate requested/client/grant scopes against the installed catalog.
+- Reject newly introduced deprecated scopes and all retired/unknown scopes.
+- Preserve deprecated scopes on an existing client's full replacement only
+  when they were already present.
+- Enforce operation authority from the catalog without implication.
+- Treat `offline_access` as a request for refresh-token-backed access while
+  retaining the server-owned issuance decision based on client capability and
+  consent policy.
+- Return unknown names so operators and UIs can diagnose drift.
+
+### Developer Portal
+
+- Render active definitions and groups from the package.
+- Render deprecated existing selections with `lifecycleNotice`; do not offer
+  them for new selection.
+- Render retired/unknown stored names as needing attention.
+- Submit concrete scope names, never group IDs.
+- Use exact matching only as a display convenience.
+
+### Authorization/consent UI
+
+- Resolve the server-approved requested names using the same pinned catalog
+  compatibility range.
+- Display groups only on exact match; otherwise display individual definitions.
+- Call out API mutation scopes from structured category and scope data, while
+  keeping the actual consent/issuance decision server-owned.
+- Fail closed on unknown or retired requested names.
+
+Consumers must not independently copy definitions or group membership. During a
+rolling deploy, the server is authoritative: it must not send a scope newly
+introduced by a catalog version that the UI deployment cannot understand. Pinning
+one exact version across a coordinated release is preferred.
+
+## Versioning and publishing
+
+Publish the catalog with `@lunch-money/v2-api-spec`. A spec-package version pins
+both the YAML and its catalog, preventing operation mappings from drifting.
+Use the change classes above when selecting the package version:
+
+- patch for copy-only and implementation fixes;
+- minor for additive catalog entries or backward-compatible API additions;
+- major only with an approved migration for a public contract break;
+- migration-requiring catalog changes may still use minor versions before 1.0,
+  but release notes and server coordination are mandatory.
+
+Start with prereleases until all three consumers validate the contract. Existing
+spec-package release tooling builds the subpath and verifies package contents
+before publishing.
+
+Each server release should pin an exact package version. Portal and consent UI
+should use the same version or a declared compatibility window validated in CI.
+Never depend on an npm `latest` lookup at application startup.
+
+## Reconciliation required with the server design
+
+Before this proposal becomes final, compare these exact artifacts:
+
+1. Scope string grammar, especially resource separators and full CRUD verbs.
+2. `identity | offline | api` categories and `active | deprecated | retired`
+   lifecycle values.
+3. Group schema and the decision to reject duplicate member sets.
+4. The discriminated exact-match result and unknown-scope handling.
+5. `scope_configuration_status` semantics, warning/error details, and whether
+   deprecated-only configuration remains `valid`.
+6. Management API request/response shapes: concrete scope names only, with no
+   persisted group authority.
+7. Full-replacement rules for preserving deprecated scopes.
+8. `offline_access` request and refresh-token issuance semantics, and
+   confirmation that OIDC identity scopes are rejected.
+9. How server `tsoa` operation requirements consume catalog mappings without
+   creating a second source of truth.
+10. Exact package versions supported by server, Portal, and consent deployments,
+    including rolling-deploy behavior.
+11. The server database's representation of unknown names and its mapping to
+    `valid | needs_attention`.
+
+The server OpenAPI management schemas should remain string-based so adding a
+catalog name does not require an API schema revision.
+
+## Recommended ENG-616 follow-up
+
+1. Reconcile this proposal with the server agent's OpenAPI and database artifacts.
+2. Confirm the V2 operation coverage/exclusion policy.
+3. Review and approve the first-cut full-CRUD inventory and descriptions; do not
+   derive authority from the older read/write draft.
+4. Check in the first canonical compatibility baseline with that inventory.
+5. Add CI that builds/tests the spec package and validates the production catalog
+   against the local V2 YAML in the chosen coverage mode.
+6. Select a prerelease version, verify the tarball, and test it through local
+   `file:` or packed dependencies in all consumers.
+7. Publish only after server, Portal, and consent UI agree on the contract and
+   rolling-version policy.

package/docs/oauth/register-client.md

@@ -0,0 +1,64 @@
+# Register an OAuth client
+
+Before you add OAuth to your application code, register an OAuth client with Lunch Money. The client identifies your application during authorization and tells Lunch Money who is requesting access, where to return the user, and which scopes the application needs.
+
+[Register a new OAuth client](/oauth/applications/new) in the Developer Portal when you are ready to begin.
+
+> [!NOTE] Development access is owner-only
+> A newly registered client starts in development. Only the Lunch Money user who owns it can authorize it until the client has been reviewed and approved.
+
+## Plan the scopes
+
+List the Lunch Money features your application will provide, then use the [OAuth scopes](/oauth/scopes) page to choose the smallest complete set of scopes those features require. Select `offline_access` only if the application needs to continue making API requests after the initial access token expires and while the user is away.
+
+If your application may support more than one Lunch Money user or budget account, always include `me:read`. After authorization, `GET /v2/me` lets your application record both the Lunch Money user's `id` and the selected budget account's `account_id`, then store the connection under the complete application-owner and Lunch Money user/account identity. The same scope is also required when your application only needs to identify one connected budget account.
+
+Scopes cannot be changed after registration. While you are developing your application, creating a replacement client is inexpensive, so let the scope set evolve as you learn what the application needs. Aim to have the application's core functionality—and its required scopes—settled before you submit the client for review.
+
+If functionality added after launch needs a scope that is not already registered, you must register a replacement client with the new complete scope set and have it reviewed before rollout. Existing authorizations do not transfer to the replacement client, so users must authorize it before they can use the new functionality. Treat that reauthorization as part of the feature launch: explain what the application can now do with their Lunch Money data and invite them to authorize the replacement client when they want to enable it.
+
+## Choose the client type
+
+Select the type based on whether your application code can keep a client secret secure:
+
+- **Confidential web client:** Choose this when a trusted server can store a client secret, including for applications that are not traditional websites but use a centralized server.
+- **Native or public client:** Choose this for standalone applications installed on a user-controlled device. These clients use PKCE without a client secret. Review the [native application guidance](/oauth/native-apps) before choosing redirects for this type.
+
+The client type cannot be changed after registration. See [OAuth concepts](/oauth/concepts#client-types-and-credentials) for more detail about the two types.
+
+## Register redirect URIs
+
+A redirect URI tells Lunch Money where to return the user after authorization. Register every callback address your application will use. Confidential web clients must match every component of a registered URI, including its scheme, host, port, path, and query string. Native-client loopback redirects use the same exact matching except that the ephemeral port is ignored.
+
+Web applications normally use an HTTPS callback. If you need a callback for local development, review the [loopback guidance](/oauth/development#local-loopback-callbacks) before registering one. Mobile and desktop applications may use a private-use scheme containing a dot, such as `app.example.demo:/oauth/callback`, or a non-loopback HTTPS link. Lunch Money checks that the HTTPS URI is well formed but does not verify an Apple or Android association file when you register it. Configure the URI as a claimed HTTPS redirect on the target platform before relying on it; see the [native redirect guidance](/oauth/native-apps#redirects).
+
+After the client is approved, you can add or replace redirect URIs in the Developer Portal without submitting another initial review. An approved confidential web client must keep a production HTTPS callback. See [after approval](/oauth/review-and-approval#after-approval).
+
+Each client can have up to 10 redirect URIs, and each URI can be up to 2,048 characters. If you reach the limit, remove a callback the application no longer uses before adding another.
+
+## Register the OAuth client
+
+Open the [new OAuth client form](/oauth/applications/new) in the Developer Portal. Then:
+
+1. Describe the application so Lunch Money users can understand who built it and what it does.
+2. Provide a monitored support email where users can reach you if authorization fails.
+3. Choose its client type.
+4. Add at least one redirect URI.
+5. Select the planned scopes.
+6. Accept the current Lunch Money API Terms of Use and select **Register OAuth client**.
+
+You can own up to 25 non-deleted OAuth clients. If you reach the limit, delete a client you no longer use before registering another.
+
+The support email must be confirmed before you can submit the client for review. If it matches your own verified Lunch Money account email, Lunch Money confirms it automatically. For any other address—including one used by another Lunch Money account—Lunch Money sends a confirmation link from `support@lunchmoney.app` to that mailbox. The link is valid for 72 hours, so use an address you can access and follow the link promptly.
+
+After registration, record the client ID in your application configuration. A client ID identifies the registration but is not a secret.
+
+If you registered a **Confidential web client**, create a client secret from its details page. Lunch Money shows the secret value only once. Copy it immediately into a secret manager or protected server configuration; it cannot be retrieved later. Never commit it or expose it in browser or mobile code.
+
+A confidential web client can have up to three non-revoked secrets. This allows you to introduce a replacement secret, update and verify the deployed application, and then revoke the old secret without interrupting authorization. Expired secrets still count toward the limit until you revoke them. Revoking an obsolete secret frees a slot, and revoked secrets no longer appear in the client's secret list. See [OAuth security guidance](/oauth/security#operate-credentials-safely) when planning ongoing rotation.
+
+You now have the client settings needed to connect your application to Lunch Money.
+
+To exercise those settings with a focused confidential-client implementation, [try OAuth with the Node.js sample](/oauth/sample-applications#try-oauth-with-your-lunch-money-account).
+
+Next: [Implement authorization](/oauth/authorization-code).

package/docs/oauth/review-and-approval.md

@@ -0,0 +1,84 @@
+# OAuth client review and approval
+
+Every new OAuth client starts in development, where only its owner can authorize it. This gives you time to build and test the application without making an unfinished integration available to other Lunch Money users.
+
+When the application is ready, submit its client for review in the Developer Portal. A Lunch Money employee reviews the application information, requested scopes, redirect configuration, and other readiness requirements. Approval moves the client to `active`, allowing other Lunch Money users to authorize the application.
+
+## Lifecycle states
+
+| State | What it means | Owner action |
+| --- | --- | --- |
+| `development` | The client has not been submitted for review; only its owner can authorize it | Configure and test, then request review. |
+| `pending_review` | Review has been requested and is waiting for or receiving review; review-critical fields are frozen | Continue owner testing or cancel the request. |
+| `active` | The review was approved; other Lunch Money users may authorize the application | Keep configuration current; identity updates reach users after Lunch Money reviews them. |
+| `rejected` | Changes were requested | Read feedback, revise editable configuration, and resubmit. |
+| `disabled` | Lunch Money disabled the client; its owner is notified, authorization is unavailable, and existing grants no longer work | Review the reason provided and contact developer support when appropriate. |
+
+Deleted clients disappear from the owner's Developer Portal.
+
+## Prepare for review
+
+Submitting a client for review is how you make your application authorizable by Lunch Money users other than yourself. Registration already requires basic information, including a support email, but review requires a complete, user-facing application profile and production-ready configuration.
+
+Before requesting review, make sure the client has:
+
+- an application description, developer name, and logo so users can identify the application and who created it;
+- a confirmed, monitored support email where users and Lunch Money can reach you;
+- a publicly accessible homepage URL where users can learn about the application;
+- a publicly accessible privacy policy URL explaining how the application handles user data;
+- at least one eligible redirect URI—a confidential web client needs a non-loopback production HTTPS redirect, while a native client may use a private-use scheme or loopback redirect;
+- a recognized, supported scope set and an explanation of why the application needs each scope; and
+- acceptance of the current Lunch Money API Terms of Use.
+
+The privacy policy must be available at a direct, stable public URL and explain how the application collects, uses, stores, shares, and deletes user data. A published privacy-policy page in a public source-code repository can satisfy this requirement. An in-app page that requires installation or sign-in, or a link to source code without a clear privacy policy, does not.
+
+Fully test the client before submission. Testing by the client owner is sufficient; submission does not require beta-tester coverage. A confidential web client also needs at least one active, non-expired secret; a native or public client does not.
+
+Explain which features use each requested scope, how that access benefits users, and why narrower scopes are insufficient. If the client includes `offline_access`, explain why the integration must operate while the user is absent. You may also provide documentation, source-code, and demonstration URLs or context about changes made after earlier feedback.
+
+Open-source applications are welcome. If your source code is public, include the repository URL in the review request's additional context. It can help the reviewer understand how your application uses Lunch Money data and the scopes it requests. Publishing source code is optional and is not required for approval.
+
+A confidential web client may retain owner-only loopback callbacks alongside its production HTTPS callback, but it still needs a non-loopback production HTTPS redirect before review.
+
+Confirm the support email from the mailbox before you submit the client. The Developer Portal's readiness checklist shows whether it is confirmed and prevents submission until it is. If you change the address before approval, Lunch Money clears its confirmation; confirm the new address before the client can be submitted or approved.
+
+### Native applications
+
+You do not need to create a standalone marketing website for a native application. Its public Apple App Store or Google Play listing can serve as the homepage if it clearly explains what the application does and identifies the developer. A public pre-release listing, project page, or README in a public source-code repository can also work.
+
+Lunch Money can approve a native client before its public App Store or Google Play release when the reviewer can access a TestFlight, other beta, or pre-release build. Use the review request's additional context to explain how to access it. Include any required opt-in steps, supported platforms or devices, and other information the reviewer needs to evaluate the application. Do not include passwords, client secrets, tokens, or other credentials.
+
+> [!NOTE] Prepare for Apple App Review
+> If the iOS app requires Lunch Money authorization, provide Apple with a dedicated test Lunch Money account in the App Store Connect review information rather than a personal account. Make sure the account and its test budget account remain available throughout review. Two-factor authentication can prevent the reviewer from signing in unless you also provide a usable authentication code or another review-ready access path in the review notes.
+
+Native clients may be reviewed with loopback or private-use scheme redirects.
+
+## Submit, cancel, or revise
+
+Submitting the request moves the client to `pending_review` and temporarily freezes review-critical fields. Reviews are usually completed within a couple of business days. You can continue developing and testing the application as the client owner while you wait. If you need to change a frozen field, cancel the request to return the client to `development`, make the change, and submit it again.
+
+You can make up to five initial review submissions across all your clients in a rolling 24-hour period. Cancelled submissions and submissions made again after a rejection still count. Deleting a client does not remove its submissions from the window. Reviews opened automatically after you update the identity of an active client do not count toward this limit.
+
+If you reach the limit, the Developer Portal tells you when you can submit again. Wait until that time before retrying; cancelling, deleting, or replacing a client does not reset the window.
+
+Lunch Money emails you when the review is complete. You can also check the current status and review history on the client's page in the Developer Portal.
+
+## If review is denied
+
+If the review is denied, the Developer Portal shows feedback explaining what needs to change. Update the client's editable configuration and submit a new review request. Editing the client alone does not resubmit it or clear the `rejected` status.
+
+There is no review comment thread, so use the new request's additional context to explain how you addressed the feedback. The Portal keeps the earlier request in the client's review history.
+
+## After approval
+
+An `active` client can be authorized by other users. Keep its configuration current in the Developer Portal. You do not need to contact Lunch Money to rename the application, move hosting, or update a support address.
+
+Changes save immediately, and the client stays `active`. Redirect URIs, description, and developer name take effect as soon as you save them. An approved confidential web client must keep at least one public HTTPS redirect.
+
+Name, logo, support email, homepage URL, and privacy policy URL also save immediately, but Lunch Money users continue to see the last approved identity on the consent screen and Connected Apps page until Lunch Money reviews the update. The Developer Portal shows that as an identity update in review; it is not a return to `rejected`, and existing authorizations keep working.
+
+When you change the support email, confirm the new address before Lunch Money can approve the identity update. Until it is confirmed and approved, users continue to see the previous approved address, and Lunch Money does not send notifications to the new address. Lunch Money tells the previously confirmed support address that the client was changed.
+
+Client-secret rotation and revocation remain available subject to lifecycle and security checks. Scopes and client type cannot be changed after registration. A scope change requires a replacement client and user reauthorization.
+
+Next: [Review the security checklist](/oauth/security).