fix(skatteverket): request the AGI kvittens scope and stop misdiagnosing the 403 (#1596)

* fix(skatteverket): request the AGI kvittens scope, not just the inlamning one

AGI is backed by two SKV APIs and each needs its own scope, but DEFAULT_SCOPES
only carried `agd`. That covers arbetsgivardeklaration/inlamning (POST underlag,
kontrollresultat, spara, skapaGranskningsunderlag), so a filing submits and
signs perfectly. The kvittens read lives on hanteraredovisningsperiod, which
requires `agdredovisningperiod`, so the flow died on its very last step with
403 {"error": "The required scopes are not authorized"}.

Confirmed against production: the same APIGW client id and secret reach the
bearer check on both APIs (401 "Token has been revoked" from each with a bogus
token), proving both subscriptions exist and the gateway contract was never the
problem, and SKV's application registration lists `agd`, `agdredovisningperiod`
and `momsdeklaration` as three separate scopes.

The body is identical to the APIGW subscription gap of #973, which is why
api-client's classification cannot distinguish the two from the string alone;
that split still needs the gateway-side check, so it is left as is.

Note the spelling `agdredovisningperiod`: no genitive s, exactly as SKV
registers it. Pinned with a scope-set regression test, since this is the third
time a scope has gone missing (#431 removed `ska` the same way) and the damage
is always invisible until a real filing fails.

The AGIPanel missing-scope banner now checks both scopes. It only looked for
`agd`, so the token shape that actually hurts, one that gets all the way
through signing before failing, produced no warning at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(skatteverket): stop blaming the APIGW subscription for a missing token scope

`{"error": "The required scopes are not authorized"}` has two causes and the
gateway never says which: our APIGW client has no subscription for the API
(#973), or the token lacks the scope that API requires. The message named only
the first, so a real production filing spent its debugging time in
Utvecklarportalen while the actual fix was a scope the code never requested.

The message now names both knobs, and says WHICH service refused. That last
part is what was really missing: the sibling inlamning API kept working
throughout, so "Skatteverket denied the call" pointed at nothing. Ruling the
two apart still needs the out-of-band test (call the API with a deliberately
invalid bearer and the same Client_Id: a subscription gap fails at the gateway
with this body, a scope gap reaches the bearer check and answers 401), which is
now documented at the predicate instead of living in someone's memory.

Classification is deliberately unchanged. ACCESS_DENIED stays out of
RECONSENT_ERROR_CODES: the scope case does need a reconnect, but only after the
scope exists, so an automatic reconsent would rebuild the self-perpetuating
banner of #1155.

This reverses one specific decision from #1250, which removed the
SKATTEVERKET_SYSTEM_SCOPES mention on the reasoning that the gateway rather
than the scope list had refused. That reasoning assumed the body could tell
them apart. It cannot. The test asserting the omission is inverted, with the
reason recorded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(salary): make the AGI kvittens-scope notice dismissible

The two AGI scopes get different treatments in AGIPanel: a token
without agd keeps the hard reconnect nudge, but a token missing only
agdredovisningperiod gets its own softer, dismissible notice. Every
existing hosted token lacks the new scope, and until Skatteverket's
application registration carries it a reconnect mints the same grant
again (SKV silently drops unregistered scope names), so a hard
reconnect demand would be the #1010 un-clearable banner, with each
futile attempt costing a BankID round-trip. Dismissal persists per
granted scope string: a futile reconnect stays quiet, a widened grant
re-evaluates from scratch.

Also asserts the shared prenumeration/scope message and the refused
API path on the 401 contract test, matching the 403 test (review nit).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Emil <emilmattsson14@gmail.com>

* fix(salary): point the kvittens-scope notice at Skatteverket's own e-service

The compliance review flagged that dismissing the notice could leave a
filer without a software-side path to the receipt. Retrieval never
depended on the notice (the kvittens cron retries server-side and the
period's status row stays unconfirmed until a kvittens lands), but the
copy now also names the fallback that always works: verifying the
receipt in Skatteverket's Arbetsgivardeklaration e-service.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Emil <emilmattsson14@gmail.com>

* fix(salary): use the ladder radius on the kvittens notice

The radius ladder guard landed on main after this notice was written;
rounded-md is dead vocabulary, bordered boxes are rounded-lg.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(salary): scope the kvittens-notice dismissal to the employer

The localStorage key carried only the granted scope string, so on a
shared browser one company's dismissal hid the notice for every other
company with an identical grant. Skatteverket tokens are per company,
so the key now includes arbetsgivare alongside the scope string; the
same-grant reconnect behavior per company is unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Signed-off-by: Emil <emilmattsson14@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Emil <emilmattsson14@gmail.com>

extensions/general/skatteverket/__tests__/api-client.test.ts

@@ -126,6 +126,31 @@ describe('skvRequest: error mapping', () => {
     }
   })
 
+  // The same body has two causes (subscription gap #973, missing token scope
+  // like the AGI kvittens one), and the gateway never says which. A message
+  // naming only the subscription sent a real prod filing down a dead end: the
+  // fix was a scope, so every minute spent in Utvecklarportalen was wasted.
+  it('names BOTH causes and the refused service on the gateway 403', async () => {
+    mockFetchStatus(403, '{"error": "The required scopes are not authorized"}')
+    try {
+      // The real shape of the incident: the kvittens read on the hantera API.
+      await skvRequest(
+        fakeSupabase, 'user-1', 'comp-1', 'GET',
+        '/arbetsgivare/165560000000/redovisningsperioder/202608/kvittenser',
+        undefined,
+        { baseUrl: 'https://api.skatteverket.se/arbetsgivardeklaration/hanteraredovisningsperiod/v1' },
+      )
+      expect.fail('expected throw')
+    } catch (e) {
+      const { message } = e as SkatteverketAuthError
+      expect(message).toMatch(/prenumeration/)
+      expect(message).toMatch(/scope/)
+      // Which service refused. Naming it is the whole point: the sibling
+      // inlamning API kept working, so "Skatteverket said no" is not a clue.
+      expect(message).toContain('arbetsgivardeklaration/hanteraredovisningsperiod/v1')
+    }
+  })
+
   it('still maps a real token-scope rejection → MISSING_SCOPE', async () => {
     // Body shape from SKV's AGI Tjänstebeskrivning v1.7 §4.1.2.2.
     mockFetchStatus(
@@ -158,10 +183,19 @@ describe('skvRequest: error mapping', () => {
       'WWW-Authenticate': 'Bearer error="invalid_scope"',
     })
     try {
-      await skvRequest(fakeSupabase, 'user-1', 'comp-1', 'GET', '/x')
+      await skvRequest(
+        fakeSupabase, 'user-1', 'comp-1', 'GET', '/x', undefined,
+        { baseUrl: 'https://api.skatteverket.se/arbetsgivardeklaration/inlamning/v1' },
+      )
       expect.fail('expected throw')
     } catch (e) {
-      expect((e as SkatteverketAuthError).code).toBe('ACCESS_DENIED')
+      const { code, message } = e as SkatteverketAuthError
+      expect(code).toBe('ACCESS_DENIED')
+      // Same shared message as the 403 contract path: both causes named plus
+      // the refused service, so the 401 shape cannot drift into vaguer text.
+      expect(message).toMatch(/prenumeration/)
+      expect(message).toMatch(/scope/)
+      expect(message).toContain('arbetsgivardeklaration/inlamning/v1')
     }
   })
 
@@ -274,10 +308,12 @@ describe('skvRequestWithAuth: system mode', () => {
     }
   })
 
-  it('403 APIGW contract error in system mode names the subscription, not the scope list', async () => {
-    // Still SYSTEM_AUTH_FAILED (run-level config either way), but the two are
-    // fixed with different knobs, so the message must not send the operator to
-    // SKATTEVERKET_SYSTEM_SCOPES when the gateway is what refused.
+  it('403 APIGW contract error in system mode names both knobs', async () => {
+    // Still SYSTEM_AUTH_FAILED (run-level config either way). This assertion
+    // is the inverse of what it was: #1250 removed the SKATTEVERKET_SYSTEM_SCOPES
+    // mention on the reasoning that the gateway, not the scope list, had
+    // refused. Production later proved the body cannot distinguish the two, so
+    // naming one and hiding the other is a coin flip presented as a diagnosis.
     mockFetchStatus(403, '{"error": "The required scopes are not authorized"}')
     try {
       await skvRequestWithAuth({ mode: 'system' }, 'GET', '/x')
@@ -285,7 +321,7 @@ describe('skvRequestWithAuth: system mode', () => {
     } catch (e) {
       expect((e as SkatteverketAuthError).code).toBe('SYSTEM_AUTH_FAILED')
       expect((e as SkatteverketAuthError).message).toMatch(/prenumeration/)
-      expect((e as SkatteverketAuthError).message).not.toMatch(/SKATTEVERKET_SYSTEM_SCOPES/)
+      expect((e as SkatteverketAuthError).message).toMatch(/SKATTEVERKET_SYSTEM_SCOPES/)
     }
   })
 

extensions/general/skatteverket/__tests__/oauth-scopes.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { buildAuthorizeUrl } from '../lib/oauth'
+
+/**
+ * Scope-set regression guard.
+ *
+ * Every entry here was added because removing it broke a live filing, and the
+ * damage is always delayed: SKV issues the token happily and the missing scope
+ * only surfaces as a 403 from the one API that needed it. A "remove unused
+ * scopes" cleanup has already cost us this twice (#431 for `ska`, and `agd`
+ * alone for AGI kvittenser). Pin them.
+ */
+describe('Skatteverket per-flow OAuth scopes', () => {
+  const originalClientId = process.env.SKATTEVERKET_OAUTH2_CLIENT_ID
+
+  beforeEach(() => {
+    process.env.SKATTEVERKET_OAUTH2_CLIENT_ID = 'test-client-id'
+  })
+
+  afterEach(() => {
+    if (originalClientId === undefined) delete process.env.SKATTEVERKET_OAUTH2_CLIENT_ID
+    else process.env.SKATTEVERKET_OAUTH2_CLIENT_ID = originalClientId
+  })
+
+  function requestedScopes(): string[] {
+    const url = new URL(buildAuthorizeUrl('https://app.example/callback', 'state-123'))
+    return (url.searchParams.get('scope') ?? '').split(' ').filter(Boolean)
+  }
+
+  it('requests both AGI scopes, one per backing API', () => {
+    // `agd` backs inlamning (submit/sign); `agdredovisningperiod` backs
+    // hanteraredovisningsperiod (kvittenser/las). A token with only the first
+    // completes a filing and then fails on "Hämta kvittens".
+    expect(requestedScopes()).toEqual(
+      expect.arrayContaining(['agd', 'agdredovisningperiod']),
+    )
+  })
+
+  it('keeps the interactive skattekonto scope', () => {
+    expect(requestedScopes()).toContain('ska')
+  })
+
+  it('keeps the momsdeklaration scope', () => {
+    expect(requestedScopes()).toContain('momsdeklaration')
+  })
+
+  it('lets an explicit scope option override the defaults', () => {
+    const url = new URL(
+      buildAuthorizeUrl('https://app.example/callback', 'state-123', { scope: 'agd' }),
+    )
+    expect(url.searchParams.get('scope')).toBe('agd')
+  })
+})

extensions/general/skatteverket/lib/api-client.ts

@@ -220,25 +220,75 @@ async function refreshTokenForUser(
 }
 
 /**
- * MuleSoft APIGW contract enforcement, observed verbatim in production:
+ * MuleSoft APIGW scope enforcement, observed verbatim in production:
  *
  *   { "error": "The required scopes are not authorized" }
  *
- * The gateway emits this when OUR APIGW client (SKATTEVERKET_APIGW_CLIENT_ID)
- * has no subscription for the API being called (#973). It is decided before
- * the bearer is ever evaluated, so it says nothing about the user's token.
+ * TWO different misconfigurations produce this one body, and they are fixed
+ * with different knobs:
  *
- * It has to be ruled out explicitly because it contains the substring
- * "required scope", which is how the SKV token-scope rejection used to be
- * detected: that collision classified every gateway 403 as MISSING_SCOPE, and
- * MISSING_SCOPE is in RECONSENT_ERROR_CODES, so a successful reconnect
- * (runPostConnectRefresh -> syncSkattekonto -> 403) instantly re-flagged the
- * token row and the reconnect banner perpetuated itself (#1155).
+ *   1. Our APIGW client (SKATTEVERKET_APIGW_CLIENT_ID) has no subscription for
+ *      the API being called (#973). Fixed in Utvecklarportalen.
+ *   2. The token is missing the scope that API requires, because the SKV
+ *      application was never registered for it, or because we never asked for
+ *      it. AGI needs `agd` for inlamning AND `agdredovisningperiod` for
+ *      hanteraredovisningsperiod; a token holding only the first files and
+ *      signs perfectly, then dies on the kvittens read. `ska` behaved the same
+ *      way for skattekonto (#431). Fixed by registering/requesting the scope
+ *      and reconnecting.
+ *
+ * The gateway will not tell us which, so neither can we: the message names
+ * both, and callers still classify it as ACCESS_DENIED. That verdict is about
+ * blast radius, not about cause. ACCESS_DENIED is deliberately NOT in
+ * RECONSENT_ERROR_CODES: guessing "reconnect" is what made a successful
+ * reconnect (runPostConnectRefresh -> syncSkattekonto -> 403) instantly
+ * re-flag the token row, so the banner perpetuated itself (#1155). Case 2 does
+ * need a reconnect, but only AFTER the scope exists, so an automatic reconsent
+ * loop would still be wrong.
+ *
+ * It also has to be ruled out before isTokenScopeRejection, which matches the
+ * substring "required scope".
+ *
+ * To tell the two apart, call the API with a deliberately invalid bearer and
+ * the same Client_Id/Client_Secret. Case 1 fails at the gateway with this same
+ * body; case 2 reaches the bearer check and answers 401 invalid/revoked token.
+ * Compare against an API the client is known to be subscribed to.
  */
 function isApigwScopeContractError(body: string): boolean {
   return /required scopes?\s+are\s+not\s+authorized/i.test(body)
 }
 
+/**
+ * The API segment of a SKV URL ("arbetsgivardeklaration/inlamning/v1"), for
+ * error messages that have to say WHICH service refused. Without it the user
+ * cannot tell which subscription or scope to go check, which is exactly the
+ * dead end the 403 message used to leave them in.
+ */
+function apiHintFromUrl(url: string): string {
+  try {
+    const parts = new URL(url).pathname.split('/').filter(Boolean)
+    return parts.length >= 1 ? parts.slice(0, 3).join('/') : url
+  } catch {
+    return url
+  }
+}
+
+/**
+ * User-facing message for the ambiguous gateway/scope refusal. Single-sourced
+ * so the 401 and 403 paths cannot drift apart.
+ */
+function apigwOrScopeMessage(url: string): string {
+  return (
+    `Skatteverket nekade anropet till tjänsten "${apiHintFromUrl(url)}". ` +
+    'Två saker ger samma svar: APIGW-klienten (SKATTEVERKET_APIGW_CLIENT_ID) ' +
+    'saknar prenumeration på tjänsten, eller så saknar anslutningen det scope ' +
+    'tjänsten kräver. Kontrollera båda i Utvecklarportalen: prenumerationen på ' +
+    'API:et, och att applikationens scope-lista täcker det. Om ett scope har ' +
+    'lagts till behöver du koppla bort och ansluta igen via Inställningar → ' +
+    'Skatteverket för att få en ny token.'
+  )
+}
+
 /**
  * A genuine token-scope rejection: the stored access token predates a scope
  * the service now requires, and only a fresh consent can widen it.
@@ -405,12 +455,7 @@ export async function skvRequestWithAuth(
     // cannot fix: SESSION_EXPIRED and MISSING_SCOPE are both reconsent codes,
     // so either verdict re-arms the banner the user just tried to clear.
     if (isApigwScopeContractError(text)) {
-      throw new SkatteverketAuthError(
-        'Skatteverkets API-gateway nekade anropet. Kontrollera att din ' +
-        'APIGW-klient (SKATTEVERKET_APIGW_CLIENT_ID) har prenumeration på ' +
-        'denna tjänst i Utvecklarportalen.',
-        'ACCESS_DENIED'
-      )
+      throw new SkatteverketAuthError(apigwOrScopeMessage(url), 'ACCESS_DENIED')
     }
 
     // OAuth's standard insufficient_scope marker. SKV sometimes emits this
@@ -466,10 +511,13 @@ export async function skvRequestWithAuth(
       lower.includes('api key') ||
       lower.includes('consumer')
     if (looksLikeApigwIssue) {
+      // Named the subscription outright: unlike the scope-contract body above,
+      // these shapes (client_id, consumer, subscription) point at the gateway
+      // client alone, so the message must not muddy it with the scope story.
       throw new SkatteverketAuthError(
-        'Skatteverkets API-gateway nekade anropet. Kontrollera att din ' +
-        'APIGW-klient (SKATTEVERKET_APIGW_CLIENT_ID) har prenumeration på ' +
-        'denna tjänst i Utvecklarportalen.',
+        `Skatteverkets API-gateway nekade anropet till "${apiHintFromUrl(url)}". ` +
+        'Kontrollera att din APIGW-klient (SKATTEVERKET_APIGW_CLIENT_ID) har ' +
+        'prenumeration på denna tjänst i Utvecklarportalen.',
         'ACCESS_DENIED'
       )
     }
@@ -483,18 +531,7 @@ export async function skvRequestWithAuth(
     // "log in again" sends them down a dead end; be explicit about the
     // likely fix instead.
     if (!text) {
-      // Extract the API segment of the URL so the message tells the user
-      // exactly which subscription is missing. Falls back to the raw URL
-      // if parsing fails.
-      let apiHint = url
-      try {
-        const u = new URL(url)
-        const parts = u.pathname.split('/').filter(Boolean)
-        // Take the first 3 segments, e.g. arbetsgivardeklaration/inlamning/v1
-        if (parts.length >= 1) apiHint = parts.slice(0, 3).join('/')
-      } catch {
-        // keep raw url
-      }
+      const apiHint = apiHintFromUrl(url)
       throw new SkatteverketAuthError(
         'Skatteverkets API-gateway nekade anropet utan motivering. ' +
         'Trolig orsak: APIGW-klienten (SKATTEVERKET_APIGW_CLIENT_ID) har ' +
@@ -529,9 +566,10 @@ export async function skvRequestWithAuth(
       // point at the scope list when the gateway is what refused.
       if (isApigwScopeContractError(text)) {
         throw new SkatteverketAuthError(
-          'Skatteverkets API-gateway nekade systemanropet: APIGW-klienten ' +
-          '(SKATTEVERKET_APIGW_CLIENT_ID) saknar prenumeration på denna ' +
-          'tjänst i Utvecklarportalen.',
+          'Skatteverket nekade systemanropet till tjänsten ' +
+          `"${apiHintFromUrl(url)}": antingen saknar APIGW-klienten ` +
+          '(SKATTEVERKET_APIGW_CLIENT_ID) prenumeration på tjänsten, eller så ' +
+          'täcker inte SKATTEVERKET_SYSTEM_SCOPES det scope tjänsten kräver.',
           'SYSTEM_AUTH_FAILED'
         )
       }
@@ -552,17 +590,13 @@ export async function skvRequestWithAuth(
         'OMBUD_GRANT_MISSING'
       )
     }
-    // Gateway contract failure, checked first: it wears scope wording but is
-    // our APIGW subscription, not the user's token. Reconnecting cannot fix
-    // it, and calling it MISSING_SCOPE made every reconnect re-flag the row
-    // (#1155). ACCESS_DENIED is deliberately not in RECONSENT_ERROR_CODES.
+    // Gateway scope enforcement, checked first: the body wears token-scope
+    // wording but names neither cause, so it must not reach
+    // isTokenScopeRejection below. ACCESS_DENIED is deliberately not in
+    // RECONSENT_ERROR_CODES (#1155): a reconnect is only the fix once the
+    // scope actually exists, so it can never be automatic.
     if (isApigwScopeContractError(text)) {
-      throw new SkatteverketAuthError(
-        'Skatteverkets API-gateway nekade anropet. Kontrollera att din ' +
-        'APIGW-klient (SKATTEVERKET_APIGW_CLIENT_ID) har prenumeration på ' +
-        'denna tjänst i Utvecklarportalen.',
-        'ACCESS_DENIED'
-      )
+      throw new SkatteverketAuthError(apigwOrScopeMessage(url), 'ACCESS_DENIED')
     }
     // Missing scope on the access token: fires when an existing connection
     // pre-dates an extension that needed a new scope (the AGI/`agd` rollout

extensions/general/skatteverket/lib/oauth.ts

@@ -38,7 +38,25 @@ const DEFAULT_OAUTH_BASE_URL = 'https://peroauth2.test.skatteverket.se/oauth2/v1
 //   - `skattekonto` is NOT a real SKV scope name: SKV silently drops it
 //                   from every grant. Kept only so a future SKV rename in
 //                   our favor costs nothing.
-const DEFAULT_SCOPES = 'momsdeklaration inkforetag skahmst skattekonto ska agd'
+//
+// AGI needs TWO scopes, one per backing API, and missing the second one is
+// invisible until the very last step of a filing:
+//   - `agd`                  = arbetsgivardeklaration/inlamning (POST underlag,
+//                              kontrollresultat, spara, skapaGranskningsunderlag).
+//   - `agdredovisningperiod` = arbetsgivardeklaration/hanteraredovisningsperiod
+//                              (kvittenser, las, lasUpp). Note the spelling:
+//                              "redovisningperiod", no genitive s, exactly as
+//                              SKV registers it. Added 2026-08-13 after a real
+//                              prod filing signed fine and then failed on
+//                              "Hämta kvittens" with 403 {"error": "The
+//                              required scopes are not authorized"}: the token
+//                              carried `agd` only, so the hantera API refused
+//                              while inlämning kept working. Same body as the
+//                              APIGW subscription gap (#973), which is why the
+//                              gateway/token distinction has to be made with
+//                              the APIGW client, not from this string alone.
+const DEFAULT_SCOPES =
+  'momsdeklaration inkforetag skahmst skattekonto ska agd agdredovisningperiod'
 
 function getOAuthBaseUrl(): string {
   return process.env.SKATTEVERKET_OAUTH_BASE_URL || DEFAULT_OAUTH_BASE_URL