@lunch-money/developer-docs 2.11.1-preview.9 → 2.11.1

package/docs/oauth/authorization-code.md

@@ -1,80 +0,0 @@
-# Implement the authorization-code flow
-
-After you [register an OAuth client](/oauth/register-client), your application uses its settings—including its client ID, client secret, and registered redirect URI—to implement the authorization flow. As shown in the [OAuth overview](/oauth), your application sends the user to Lunch Money, Lunch Money returns an authorization code to your callback, and your application exchanges that code for tokens.
-
-This guide walks through that process for a **Confidential web client**. Your server handles the callback and token exchange and keeps the client secret and refresh tokens secure. If you are building a standalone mobile or desktop application, read the [native application guidance](/oauth/native-apps) instead.
-
-## Choose an OAuth library
-
-OAuth libraries handle much of the protocol work for you, including generating PKCE values, building authorization requests, validating callback state, and exchanging authorization codes. Choose a well-maintained OAuth 2.0 client library for your language and application framework. Look for support for:
-
-- the authorization-code flow with Proof Key for Code Exchange (PKCE);
-- OAuth authorization-server metadata discovery;
-- secure `state` generation and validation; and
-- confidential-client authentication with HTTP Basic.
-
-For Node.js and TypeScript, [`openid-client`](https://github.com/panva/openid-client) is one maintained option. Despite its name, using it does not mean that Lunch Money supports OpenID Connect identity scopes, ID tokens, or UserInfo.
-
-## Configure Lunch Money with discovery
-
-Your OAuth library needs to know where to send the user for authorization, where to exchange codes for tokens, and which protocol features Lunch Money supports. Instead of configuring each value separately, give the library the Lunch Money issuer:
-
-`https://api.lunchmoney.dev`
-
-Then have it load the OAuth authorization-server metadata document:
-
-`https://api.lunchmoney.dev/.well-known/oauth-authorization-server`
-
-The metadata document is a machine-readable description of Lunch Money's authorization, token, and revocation endpoints, supported client-authentication methods, and PKCE method. Using it allows your library to obtain the current OAuth configuration without your application assembling endpoint URLs itself.
-
-> [!TIP]
-> The resolved endpoint paths are `/oauth/authorize`, `/oauth/token`, and `/oauth/revoke`. These are useful when debugging, but use metadata discovery when your library supports it.
-
-## 1. Start authorization
-
-On your server, generate:
-
-- a cryptographically random `state` value bound to the user's session;
-- a PKCE `code_verifier`; and
-- its `S256` `code_challenge`.
-
-Redirect the browser to the discovered authorization endpoint with `response_type=code`, your `client_id`, exact `redirect_uri`, `state`, `code_challenge`, and `code_challenge_method=S256`.
-
-> [!NOTE] Scopes come from the client registration
-> You do not need to send `scope`. If your OAuth library includes it, Lunch Money ignores the requested value and uses the client's complete registered scope set. An authorization request cannot narrow or expand that set; changing scopes requires a replacement client.
-
-## 2. Handle the callback
-
-The callback receives either `code` and `state`, or an OAuth `error` and the original `state`. Before exchanging a code:
-
-1. compare `state` with the one-time value stored in the initiating session;
-2. reject missing, mismatched, or reused state;
-3. reject unexpected issuer or callback parameters;
-4. consume the stored state and PKCE verifier once; and
-5. remove authorization parameters from the visible browser URL before rendering a page.
-
-Treat `access_denied` as a normal user decision. Do not log the callback query string.
-
-## 3. Exchange the code
-
-Send a form-encoded request to the discovered token endpoint with `grant_type=authorization_code`, the code, exact `redirect_uri`, and original `code_verifier`. A confidential client authenticates with HTTP Basic using its client ID and secret. Do this server-side.
-
-Store `access_token`, `token_type`, granted `scope`, and expiration metadata securely. If a `refresh_token` is returned, keep it server-side as a high-value credential.
-
-## 4. Call the API
-
-Send the access token in the header:
-
-```http
-GET /v2/me HTTP/1.1
-Host: api.lunchmoney.dev
-Authorization: Bearer YOUR_ACCESS_TOKEN
-```
-
-The operation must be allowed by the token's scope and by the user's access to the selected budgeting account. See the [scope catalog](/oauth/scopes).
-
-## 5. Continue or recover
-
-Use the response's `expires_in` value to schedule renewal slightly before expiry. Read [token lifecycle and recovery](/oauth/tokens) before implementing refresh, logout, or revocation.
-
-Next: [Develop and test your OAuth application](/oauth/development).

package/docs/oauth/concepts.md

@@ -1,46 +0,0 @@
-# OAuth concepts
-
-These terms describe who participates in Lunch Money OAuth and what each credential can do.
-
-## Parties in the flow
-
-- **User (resource owner):** the Lunch Money user who authorizes a third-party application to make API requests on their behalf for one budgeting account.
-- **Application:** the complete product or service the developer builds. It may contain many features unrelated to Lunch Money; only its Lunch Money OAuth client is managed in the Developer Portal.
-- **Client:** the application's OAuth registration with Lunch Money: its `client_id`, type, redirect URIs, selected scopes, and—when applicable—client secret. The developer must register this client in the Developer Portal before the application can ask Lunch Money users to authorize API access.
-- **Authorization server:** the Lunch Money-owned service that presents the Lunch Money sign-in and consent screens, records the user's decision, and issues authorization codes and tokens. The user signs in directly with Lunch Money; the third-party application never receives or sees their Lunch Money login credentials.
-- **Lunch Money API service:** the Lunch Money-owned V2 API, which receives the application's API requests, accepts access tokens, and checks that each request is permitted by the client's scopes.
-
-## Client types and credentials
-
-When a developer registers a client, they must choose a client type based on whether the application code can keep a client secret secure. This choice cannot be changed after the client is registered. The developer selects either **Confidential web client** or **Native or public client**.
-
-- **Confidential web client:** Runs on a server and can securely store client secrets. In OAuth terminology, this is called a *confidential client*. Choose this type for a web application—or any other application architecture with a centralized server. Its client secret helps Lunch Money verify that a token request came from the application that registered the client. The client secret and refresh tokens must stay on the server. The application must protect access tokens wherever its architecture uses them, and associate each authorization with the correct application user and authorized Lunch Money budgeting account.
-- **Native or public client:** Runs on a user-controlled device and uses PKCE without a client secret because installed application code cannot keep a secret secure. In OAuth terminology, this is called a *native public client*. Choose this type for a standalone mobile or desktop application. The app stores each user's tokens securely on that user's device—for example, in Keychain on Apple platforms or appropriate Keystore-backed storage on Android—and must avoid exposing them through backups, logs, or application data shared with other apps.
-
-Every client receives a client ID that identifies its Lunch Money registration. The client ID is not secret. Both client types also use Proof Key for Code Exchange (PKCE) to bind the authorization response to the application that started the flow.
-
-## Redirect URIs
-
-A redirect URI is the callback address where the Lunch Money authorization server returns control to the application after the user approves or denies access. Lunch Money redirects the user's browser to that address with either a temporary authorization code or information about why authorization did not complete.
-
-The developer registers each permitted redirect URI in advance. For a confidential web client, the URI sent at the start of authorization must exactly match one of those registered values, including its scheme, host, port, path, and query string. A native client's loopback redirect follows the same rule except that its ephemeral port is ignored. Fragments are not allowed. These checks prevent an authorization result from being redirected to an unexpected destination. The application's callback must also avoid acting as an open redirect to another location.
-
-## Scopes and least privilege
-
-Resource scopes such as `transactions:read` authorize specific ways of working with Lunch Money data. A scope generally applies to a particular kind of action—such as reading or updating a resource—and only to the relevant API endpoints. Permissions are independent: for example, `transactions:update` does not also grant `transactions:read`.
-
-The [V2 API reference](/v2/docs) identifies the scope required by each API endpoint. Use it together with the [scope catalog](/oauth/scopes) to select the permissions your application's features require.
-
-Scopes are selected when the client is created and cannot be edited later. Every user who authorizes that client sees and grants all—and only—the scopes the developer selected. To change them, create and test a replacement client, complete review when applicable, update your integration, and ask existing users to authorize again. Existing authorizations and tokens do not move to the replacement client.
-
-Select `offline_access` when your application needs to continue making API requests on a user's behalf for longer than the brief period covered by the initial access token. It allows the application to receive a refresh token, which it can use to maintain access without repeatedly asking the user to sign in and authorize the application. It does not add permission to read or change any Lunch Money data; the client still needs the relevant resource scopes.
-
-## Codes and tokens
-
-- An **authorization code** is the short-lived, single-use value Lunch Money sends to the application's callback after the user approves access. The code cannot make API requests by itself. Every client exchanges it at Lunch Money's token endpoint using its PKCE verifier. A confidential client must also authenticate that request with its client ID and client secret. Lunch Money then returns an access token and, when applicable, a refresh token.
-- An **access token** is a credential the application sends as part of each V2 API request. It is relatively short-lived. The token response includes `expires_in`, the number of seconds for which the access token is expected to remain valid, so the application can record when it will expire and obtain a replacement when needed.
-- A **refresh token** is a longer-lived but non-permanent credential available only to clients that selected `offline_access`. The application sends it to Lunch Money's token endpoint to request a new access token and replacement refresh token without asking the user to authorize again.
-
-An application can refresh its access token shortly before it expires or wait until an API response indicates that the access token is no longer valid. If the application does not have a refresh token—or if that token expires, is revoked, or otherwise stops working—it must ask the user to authorize again.
-
-Next: [Register an OAuth client](/oauth/register-client).

package/docs/oauth/development.md

@@ -1,57 +0,0 @@
-# Develop and test an OAuth application
-
-Use this guide after you have [registered a client](/oauth/register-client) and implemented the [authorization flow](/oauth/authorization-code). At this stage, your application should be able to send its owner to Lunch Money, receive an authorization code at its callback, exchange the code for tokens, and make an API request.
-
-The goal now is to test that complete workflow—including its failure and recovery paths—before asking Lunch Money to approve the application for other users.
-
-> [!NOTE] Development access is owner-only
-> While an OAuth client is in development, only the Lunch Money user who owns it can authorize the application. Your team should have the developer doing most of the initial Lunch Money work create and own the client so they can test the complete flow with their budgeting accounts. Other team members cannot authorize the application until the client has been reviewed and approved.
-
-## Set up a safe test environment
-
-Use a separate Lunch Money test budgeting account when exercising create, update, or delete operations. The [Getting Started guide](/getting-started#create-a-test-budgeting-account) walks through creating one and adding sample data.
-
-Keep production client secrets, tokens, and user data out of test fixtures, logs, screenshots, and bug reports.
-
-## Local loopback callbacks
-
-When you run a confidential web application on your own computer, its callback handler may not have a public HTTPS address yet. A loopback redirect lets the browser return the authorization result directly to the local process you are developing.
-
-For a client in development, register an HTTP redirect using a supported loopback host and the port and path where your application listens:
-
-- Hostname: `http://localhost:43821/callback`
-- IPv4: `http://127.0.0.1:43821/callback`
-- IPv6: `http://[::1]:43821/callback`
-
-You may choose any available port, but the complete redirect URI sent during authorization must match the registered value exactly. `localhost` and `127.0.0.1` are different hosts, so register the form your application sends. Non-loopback HTTP hosts, embedded credentials, and URI fragments are not supported.
-
-The user's browser—not Lunch Money's server—connects to the loopback listener. Keep PKCE and `state` protections in place just as you would for a hosted callback. Before requesting review, also register the HTTPS callback used by the deployed application; the loopback URI can remain available for local testing.
-
-> [!NOTE] Test an approved client with your development team
-> After a client is approved, other team members can continue developing and testing the application's Lunch Money functionality. If the approved client has a loopback redirect registered, each developer who can run the application locally may authorize access to their own Lunch Money budgeting account. The client ID is public, but developers working on a confidential web client also need access to its client secret through your team's secure credential-management process. Do not share access tokens or refresh tokens between developers.
-
-## Repeat or reset authorization
-
-During development, the client owner can run authorization again whenever they want to repeat the sign-in, budgeting-account selection, consent, and callback flow. They do not need to revoke the current token first; a new successful authorization replaces their previous active authorization for that client.
-
-To test how the application responds after access is revoked, revoke the current token and make another API request with it. Lunch Money should reject the request, and the application should discard its saved credentials and begin authorization again. The [token revocation guide](/oauth/tokens#revoke-access) includes copyable `curl` requests for development testing.
-
-## Test the complete client
-
-1. Complete authorization. For each attempt, your application should create a random `state` value, save it with the application user's session, and verify that Lunch Money returns the same value to the callback. Rejecting a missing, changed, or reused value prevents a callback started elsewhere from being attached to the wrong session.
-2. Keep the PKCE verifier with that same authorization attempt and use it when exchanging the returned code. Confirm that an exchange with a missing or changed verifier fails; this prevents someone who intercepts the code from using it.
-3. Read the token response's `scope` field and confirm that it contains the complete scope set registered for the client. Do not inspect or parse the access token itself.
-4. Call every scope-dependent feature, including negative permission cases.
-5. Test user denial, missing or changed `state`, callback errors, and interrupted authorization attempts.
-
-## Test reauthorization before refresh
-
-First make sure your application can recover without a refresh token. Record when the token response arrives and use `expires_in` to determine when the access token is expected to expire. After it expires, make a harmless API request and confirm that Lunch Money returns an authentication failure identifying the token as invalid.
-
-Your application should discard the unusable token and start authorization again. Confirm that the same application user can complete the flow, select a budgeting account, and continue using the application with the replacement token. This recovery path is required when a client does not have `offline_access`, and it remains the fallback when a refresh token expires, is revoked, or otherwise stops working.
-
-After reauthorization works, clients registered with `offline_access` can add and test refresh-token handling. Verify replacement-token storage, concurrent-refresh protection, revocation, and terminal refresh recovery before relying on unattended operation. See [token lifecycle and recovery](/oauth/tokens).
-
-Finally, add a production HTTPS redirect and complete the [review checklist](/oauth/review-and-approval).
-
-Next: [Operate securely](/oauth/security).

package/docs/oauth/index.md

@@ -1,28 +0,0 @@
-# OAuth for Lunch Money integrations
-
-OAuth lets your application access Lunch Money on behalf of a user without asking that person to copy and share a personal access token. **If you are building an application for anyone other than yourself, use OAuth.** It gives each user a familiar Lunch Money sign-in and consent experience while keeping their personal access token out of your application.
-
-![OAuth authorization-code flow across your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser, Lunch Money handles sign-in and presents the budgeting-account and permission choices, the user approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens and calls the API.](/v2/images/oauth-authorization-flow.svg)
-
-## Choose OAuth or a personal access token
-
-| Question | Personal access token | OAuth application and client |
-| --- | --- | --- |
-| Whose data can it access? | One budgeting account belonging to the user who created the token | One budgeting account selected by each user who authorizes the application |
-| Best fit | API exploration, one-off scripts, and short-lived work on your own account | Persistent integrations and applications intended for other users |
-| How is access granted? | The user creates a token on the [Developers page](https://my.lunchmoney.app/developers) in the Lunch Money web app | The user signs in and approves the permissions requested by the application |
-| Credential handling | The user keeps the token and sends it with their own API requests; third-party applications should use OAuth instead of asking users to share one | The authorization flow delivers application-specific tokens without asking for a personal token |
-| Permissions | Full access to the Lunch Money APIs available for that budgeting account, with no fine-grained permission controls | Only the permissions selected when the application was created |
-| Lifecycle | Created and revoked by the user | Short-lived access tokens and optional finite refresh access; the user can revoke the application's access |
-
-Personal access tokens remain useful for quick work on your own account. OAuth is the recommended model for applications and integrations that other Lunch Money users will connect to, as well as automations that need to run over time.
-
-## What limits access
-
-When a developer creates an OAuth application, they select the scopes—the specific permissions—the application needs. Later, when a Lunch Money user authorizes the application, Lunch Money shows them that complete permission set before they approve access. Choose only the permissions the application's features require. A focused permission request is easier for users to understand and trust, and reduces the risk of the application reading or changing data it does not need.
-
-## Before you start
-
-You need an active Lunch Money account to [register and manage an OAuth application](/oauth/applications). During development, only the application owner can authorize it. Approval is required before other Lunch Money users can authorize it.
-
-Start with [OAuth concepts](/oauth/concepts), [register a client](/oauth/register-client), and then [implement the authorization-code flow](/oauth/authorization-code). Use the [scope catalog](/oauth/scopes) to plan permissions and [troubleshooting](/oauth/troubleshooting) when a flow fails.

package/docs/oauth/native-apps.md

@@ -1,26 +0,0 @@
-# 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. Custom schemes must be distinctive and protected against interception.
-
-The loopback callbacks supported for confidential web development do not define native or desktop redirect support. Follow the native redirect choices accepted during client registration; do not assume the confidential web-client loopback rules apply.
-
-## 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

@@ -1,370 +0,0 @@
-# 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`.
-- Let `transactions:read` expose attachment IDs and metadata, while requiring
-  explicit `transaction_attachments:*` scopes to download, attach, or delete
-  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.