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

package/docs/oauth/native-apps.md

@@ -0,0 +1,26 @@
+# 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.
+
+## 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 Universal Links 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.
+
+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.
+
+## Store and renew tokens
+
+Store tokens in Keychain on Apple platforms. On Android, use current Keystore-backed storage guidance from your maintained library; do not start new work with deprecated `EncryptedSharedPreferences` APIs. Coordinate refresh-token use, persist replacements, and fall back to interactive authorization after terminal failure.
+
+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. Full Lunch Money Swift and Kotlin sample apps are not part of this documentation phase; the upstream AppAuth projects provide maintained platform examples.
+
+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,52 @@
+# 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 permissions 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 permissions
+
+List the Lunch Money features your application will provide, then use the [scope catalog](/oauth/scopes) to choose the smallest complete set of permissions 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.
+
+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 permissions—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 verified HTTPS link accepted by the Developer Portal.
+
+## 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**.
+
+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 multiple active secrets. This allows you to introduce a replacement secret, update and verify the deployed application, and then revoke the old secret without interrupting authorization. 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.
+
+Next: [Implement authorization](/oauth/authorization-code).

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

@@ -0,0 +1,69 @@
+# 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 permissions, 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 | Operate within the approved identity and scope set. |
+| `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 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 permission; 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. 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 permission, 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 permissions 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.
+
+### 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.
+
+If you provide a pre-release listing or beta-testing link, 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.
+
+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.
+
+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. Reviewed identity fields, redirect configuration, and the registered scope set remain frozen after approval. Client-secret rotation and revocation remain available subject to lifecycle and security checks.
+
+For an exceptional identity or configuration change, contact [developer support](mailto:developer-support@lunchmoney.app). A scope change always requires a replacement client and user reauthorization.
+
+Next: [Review the security checklist](/oauth/security).

package/docs/oauth/scopes.md

@@ -0,0 +1,104 @@
+# OAuth scopes
+
+Choose the smallest complete set of permissions your application needs. This page is generated from the published `@lunch-money/v2-api-spec/oauth-scopes` catalog; do not edit it by hand.
+
+> [!NOTE] Scopes are fixed when you create a client
+> Authorization requests omit `scope`. To change permissions later, create and review a replacement client, update your integration, and ask every user to authorize it.
+
+## Scope groups
+
+Groups are selection shortcuts, not extra permissions. A group expands to the exact scopes listed below.
+
+### Read only
+
+View all supported Lunch Money data without changing it
+
+[`me:read`](#scope-me-read), [`summary:read`](#scope-summary-read), [`categories:read`](#scope-categories-read), [`crypto_manual:read`](#scope-crypto-manual-read), [`crypto_synced:read`](#scope-crypto-synced-read), [`balance_history:read`](#scope-balance-history-read), [`manual_accounts:read`](#scope-manual-accounts-read), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`transactions:read`](#scope-transactions-read), [`transaction_attachments:read`](#scope-transaction-attachments-read), [`tags:read`](#scope-tags-read), [`recurring_items:read`](#scope-recurring-items-read), [`budgets:read`](#scope-budgets-read)
+
+### Transactions
+
+Import, export, organize, and manage transactions and their attachments
+
+[`transactions:read`](#scope-transactions-read), [`transactions:create`](#scope-transactions-create), [`transactions:update`](#scope-transactions-update), [`transactions:delete`](#scope-transactions-delete), [`transaction_attachments:read`](#scope-transaction-attachments-read), [`transaction_attachments:create`](#scope-transaction-attachments-create), [`transaction_attachments:delete`](#scope-transaction-attachments-delete), [`categories:read`](#scope-categories-read), [`tags:read`](#scope-tags-read), [`manual_accounts:read`](#scope-manual-accounts-read), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`recurring_items:read`](#scope-recurring-items-read)
+
+### Budgeting
+
+Analyze and manage budgets, categories, and tags
+
+[`summary:read`](#scope-summary-read), [`budgets:read`](#scope-budgets-read), [`budgets:update`](#scope-budgets-update), [`budgets:delete`](#scope-budgets-delete), [`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read)
+
+### Accounts
+
+Manage accounts, balances, and balance history
+
+[`manual_accounts:read`](#scope-manual-accounts-read), [`manual_accounts:create`](#scope-manual-accounts-create), [`manual_accounts:update`](#scope-manual-accounts-update), [`manual_accounts:delete`](#scope-manual-accounts-delete), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`plaid_accounts:update`](#scope-plaid-accounts-update), [`crypto_manual:read`](#scope-crypto-manual-read), [`crypto_manual:create`](#scope-crypto-manual-create), [`crypto_manual:update`](#scope-crypto-manual-update), [`crypto_manual:delete`](#scope-crypto-manual-delete), [`crypto_synced:read`](#scope-crypto-synced-read), [`crypto_synced:update`](#scope-crypto-synced-update), [`balance_history:read`](#scope-balance-history-read), [`balance_history:update`](#scope-balance-history-update), [`balance_history:delete`](#scope-balance-history-delete)
+
+### Organize
+
+Manage categories and tags used to organize transactions
+
+[`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read)
+
+### Full access
+
+View and manage all supported Lunch Money data
+
+[`me:read`](#scope-me-read), [`me:update`](#scope-me-update), [`summary:read`](#scope-summary-read), [`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`crypto_manual:read`](#scope-crypto-manual-read), [`crypto_manual:create`](#scope-crypto-manual-create), [`crypto_manual:update`](#scope-crypto-manual-update), [`crypto_manual:delete`](#scope-crypto-manual-delete), [`crypto_synced:read`](#scope-crypto-synced-read), [`crypto_synced:update`](#scope-crypto-synced-update), [`balance_history:read`](#scope-balance-history-read), [`balance_history:update`](#scope-balance-history-update), [`balance_history:delete`](#scope-balance-history-delete), [`manual_accounts:read`](#scope-manual-accounts-read), [`manual_accounts:create`](#scope-manual-accounts-create), [`manual_accounts:update`](#scope-manual-accounts-update), [`manual_accounts:delete`](#scope-manual-accounts-delete), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`plaid_accounts:update`](#scope-plaid-accounts-update), [`transactions:read`](#scope-transactions-read), [`transactions:create`](#scope-transactions-create), [`transactions:update`](#scope-transactions-update), [`transactions:delete`](#scope-transactions-delete), [`transaction_attachments:read`](#scope-transaction-attachments-read), [`transaction_attachments:create`](#scope-transaction-attachments-create), [`transaction_attachments:delete`](#scope-transaction-attachments-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read), [`budgets:read`](#scope-budgets-read), [`budgets:update`](#scope-budgets-update), [`budgets:delete`](#scope-budgets-delete)
+
+## Resource scopes
+
+| Scope | What it allows | V2 operations |
+| --- | --- | --- |
+| <a id="scope-me-read"></a>`me:read` | View your Lunch Money identity and account, user, and budget settings | `getMe`, `getAccountSettings`, `getUserSettings`, `getUserAccountSettings` |
+| <a id="scope-me-update"></a>`me:update` | Update your Lunch Money account, user, and budget settings | `updateAccountSettings`, `updateUserSettings`, `updateUserAccountSettings` |
+| <a id="scope-summary-read"></a>`summary:read` | View your budget summary | `getBudgetSummary` |
+| <a id="scope-categories-read"></a>`categories:read` | View categories and category groups | `getAllCategories`, `getCategoryById` |
+| <a id="scope-categories-create"></a>`categories:create` | Create categories and category groups | `createCategory` |
+| <a id="scope-categories-update"></a>`categories:update` | Update categories and category groups | `updateCategory` |
+| <a id="scope-categories-delete"></a>`categories:delete` | Delete categories and category groups | `deleteCategory` |
+| <a id="scope-crypto-manual-read"></a>`crypto_manual:read` | View supported cryptocurrencies and manually managed cryptocurrency balances | `getAllCryptocurrencies`, `getAllCryptoManual`, `getCryptoManualById` |
+| <a id="scope-crypto-manual-create"></a>`crypto_manual:create` | Add supported cryptocurrencies and create manually managed cryptocurrency balances | `createCryptocurrency`, `createCryptoManual` |
+| <a id="scope-crypto-manual-update"></a>`crypto_manual:update` | Update manually managed cryptocurrency balances | `updateCryptoManual` |
+| <a id="scope-crypto-manual-delete"></a>`crypto_manual:delete` | Delete manually managed cryptocurrency balances | `deleteCryptoManual` |
+| <a id="scope-crypto-synced-read"></a>`crypto_synced:read` | View synced cryptocurrency accounts and balances | `getAllCryptoSynced`, `getCryptoSyncedById`, `getCryptoSyncedBalanceBySymbol` |
+| <a id="scope-crypto-synced-update"></a>`crypto_synced:update` | Refresh balances for synced cryptocurrency accounts | `refreshCryptoSynced` |
+| <a id="scope-balance-history-read"></a>`balance_history:read` | View balance history for accounts and synced cryptocurrency balances | `getBalanceHistory`, `getBalanceHistoryForAccount`, `getBalanceHistoryForCryptoSynced` |
+| <a id="scope-balance-history-update"></a>`balance_history:update` | Create or update balance history and details for deleted accounts | `upsertBalanceHistoryForAccount`, `upsertBalanceHistoryForCryptoSynced`, `updateBalanceHistoryDetails` |
+| <a id="scope-balance-history-delete"></a>`balance_history:delete` | Delete balance history for accounts and synced cryptocurrency balances | `deleteBalanceHistoryForAccount`, `deleteBalanceHistoryForCryptoSynced`, `deleteBalanceHistoryEntry` |
+| <a id="scope-manual-accounts-read"></a>`manual_accounts:read` | View manually managed accounts | `getAllManualAccounts`, `getManualAccountById` |
+| <a id="scope-manual-accounts-create"></a>`manual_accounts:create` | Create manually managed accounts | `createManualAccount` |
+| <a id="scope-manual-accounts-update"></a>`manual_accounts:update` | Update manually managed accounts | `updateManualAccount` |
+| <a id="scope-manual-accounts-delete"></a>`manual_accounts:delete` | Delete manually managed accounts | `deleteManualAccount` |
+| <a id="scope-plaid-accounts-read"></a>`plaid_accounts:read` | View accounts connected through Plaid | `getAllPlaidAccounts`, `getPlaidAccountById` |
+| <a id="scope-plaid-accounts-update"></a>`plaid_accounts:update` | Request a Plaid account refresh, which may import new transactions | `triggerPlaidAccountFetch` |
+| <a id="scope-transactions-read"></a>`transactions:read` | View transactions, including split and group information | `getAllTransactions`, `getTransactionById` |
+| <a id="scope-transactions-create"></a>`transactions:create` | Create transactions | `createNewTransactions` |
+| <a id="scope-transactions-update"></a>`transactions:update` | Update, split, unsplit, group, and ungroup transactions | `updateTransactions`, `updateTransaction`, `groupTransactions`, `ungroupTransactions`, `splitTransaction`, `unsplitTransaction` |
+| <a id="scope-transactions-delete"></a>`transactions:delete` | Delete transactions | `deleteTransactions`, `deleteTransactionById` |
+| <a id="scope-transaction-attachments-read"></a>`transaction_attachments:read` | View transaction attachment metadata and get download access to attachments | `getTransactionAttachmentUrl` |
+| <a id="scope-transaction-attachments-create"></a>`transaction_attachments:create` | Attach files to transactions | `attachFileToTransaction` |
+| <a id="scope-transaction-attachments-delete"></a>`transaction_attachments:delete` | Delete transaction attachments | `deleteTransactionAttachment` |
+| <a id="scope-tags-read"></a>`tags:read` | View tags | `getAllTags`, `getTagById` |
+| <a id="scope-tags-create"></a>`tags:create` | Create tags | `createTag` |
+| <a id="scope-tags-update"></a>`tags:update` | Update tags | `updateTag` |
+| <a id="scope-tags-delete"></a>`tags:delete` | Delete tags | `deleteTag` |
+| <a id="scope-recurring-items-read"></a>`recurring_items:read` | View recurring items | `getAllRecurring`, `getRecurringById` |
+| <a id="scope-budgets-read"></a>`budgets:read` | View budget period settings | `getBudgetSettings` |
+| <a id="scope-budgets-update"></a>`budgets:update` | Create or update budget amounts | `upsertBudget` |
+| <a id="scope-budgets-delete"></a>`budgets:delete` | Delete budget amounts | `deleteBudget` |
+
+## Continued access
+
+<a id="scope-offline-access"></a>
+
+### `offline_access`
+
+Allow this app to maintain access without asking you to sign in and authorize it again
+
+`offline_access` is not permission to a V2 resource. It allows an eligible token response to include a longer-lived, finite refresh token. Your application must still request every resource scope it needs when the client is created.
+
+## Find the scope for an endpoint
+
+The [V2 API reference](/v2/docs) displays the required OAuth scope for each operation. Scope requirements come from the same catalog and standard OpenAPI security metadata used to generate this page.
+
+Next: [Implement the authorization-code flow](/oauth/authorization-code).