Krav: forvalte tilgangskatalogen gjennom API, med eget nivå for dokumentasjon (BRU-TIL-KAT-001/002)

krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.design.md

@@ -0,0 +1,114 @@
+# Designnotat: Forvalte tilgangskatalogen
+
+**Relaterte features:**
+[`forvalte_tilgangskatalogen.feature`](./forvalte_tilgangskatalogen.feature) (BRU-TIL-KAT-001) og
+[`oppdatere_tilgangsbeskrivelser.feature`](./oppdatere_tilgangsbeskrivelser.feature)
+(BRU-TIL-KAT-002).
+
+Kravene er besluttet: tilgangskatalogen skal kunne forvaltes gjennom API, med to rettighetsnivåer.
+Notatet forklarer hvorfor skillet går der det går, hva som må håndheves hvor, og hvilke to hull i
+dagens modell kravene forutsetter blir tettet.
+
+## Hva katalogen er
+
+Katalogen er listen over tilgangene som finnes: en kode som identifiserer hver tilgang, og en
+beskrivelse av hva den gir. Den er referansepunktet for resten av tilgangsstyringen — en tildeling,
+et delegeringstak og et nekt navngir alle en tilgang fra katalogen.
+
+To egenskaper former kravene:
+
+- **En rad i katalogen gir ingen noe.** Å opprette en tilgang er å innføre et begrep, ikke å dele
+  ut noe. Først en tildeling gjør den til en tilgang noen har. Det er grunnen til at katalogen kan
+  få en skriveflate uten at flaten i seg selv er en tilgangsutvidelse.
+- **Koden er identiteten.** Alt annet peker på koden, så en kode som endres er en referanse som
+  brytes. Koden settes ved opprettelse og står.
+
+## Skillet: begrepet og forklaringen
+
+Kravene deler katalogen i to på tvers av rader, ikke på tvers av tilganger:
+
+| Nivå | Hva rettigheten omfatter | Hvem |
+|------|--------------------------|------|
+| Forvaltning | Opprette en tilgang, endre den, ta den ut av bruk | Utviklere hos Sikt |
+| Dokumentasjon | Oppdatere beskrivelsen — og ingenting annet | Bidragsytere til dokumentasjonen |
+
+Begrunnelsen for det andre nivået er at dokumentasjonen av en tilgang er den delen som eldes
+raskest og som færrest har forutsetning for å skrive. Den som kan fagområdet vet hva en tilgang
+faktisk gir; den som forvalter modellen vet hva raden gjør. Uten et eget nivå må all
+dokumentasjonsforbedring gå gjennom dem som kan endre modellen, og da blir den ikke gjort.
+
+Risikoen ved å utvide kretsen er lav, og det er verdt å si hvorfor presist: **en beskrivelse er
+ikke lest av autorisasjonen.** Ingen får eller mister tilgang av at teksten endres, ingen tildeling
+berøres, og ingen annen del av modellen peker på beskrivelsen. Det verste utfallet er en misvisende
+forklaring — som er en dokumentasjonsfeil, ikke en sikkerhetsfeil.
+
+## Kolonneskopet er et håndhevingskrav
+
+Det viktigste å ta med videre fra dette notatet: at dokumentasjonsrettigheten bare omfatter
+beskrivelsen er et krav til **håndhevingen**, ikke til hvilke felter en flate viser.
+
+En flate som skjuler kodefeltet, over et API som tar imot hele katalograden, oppfyller ikke kravet.
+Da er avgrensningen bare en presentasjon, og enhver klient som snakker med API-et direkte står
+utenfor den. Kravet er at forsøket avvises der regelen bor — i API-et og i datalaget — uansett
+hvilken inngang det kommer fra, og også når det følger med i den samme forespørselen som en gyldig
+beskrivelsesendring. Featuren har egne scenarioer for begge formene, fordi det er nettopp de to som
+skiller et håndhevet kolonneskop fra et presentert et.
+
+Praktisk konsekvens for utformingen: dokumentasjonsnivået bør ha sin **egen operasjon** som bare
+tar imot en kode og en beskrivelse, framfor å dele en generell endringsoperasjon med
+forvaltningsnivået og filtrere på rettighet inne i den. Da er kolonneskopet en egenskap ved
+grensesnittet i stedet for en regel noen må huske å håndheve.
+
+## Hullet kravene forutsetter tettet, nr. 1: katalogen kan ikke listes
+
+Ingen av dagens innganger til katalogen viser den i sin helhet. De listene som finnes er avledet av
+noe annet — tilgangene en applikasjon har, tilgangene jeg selv har, tilgangene jeg har rettighet
+til å tildele. En tilgang som ennå ikke er tildelt noen finnes dermed i modellen, men er usynlig i
+løsningen.
+
+Det er et hull for begge nivåene. Forvalteren kan ikke se hva katalogen inneholder før hun
+oppretter noe nytt, og den som skal dokumentere kan ikke finne fram til de tilgangene som mangler
+en beskrivelse — som er nøyaktig dem arbeidet handler om. Kravet er derfor en egen listespørring
+over hele katalogen, paginert og forutsigbart sortert, lesbar for begge nivåene.
+
+Paginering er tatt med i kravet framfor å overlates til utformingen, fordi katalogen er en liste
+som vokser og som ingen naturlig avgrenser: den har verken organisasjon eller miljø å filtrere på.
+
+## Hullet kravene forutsetter tettet, nr. 2: en tilgang kan ikke tas ut av bruk
+
+Katalogen har i dag ingen livsløpsmarkør. En rad består av kode, beskrivelse og sporing av hvem som
+opprettet og endret den — det finnes ingen gyldighetsperiode og ingen «utgått»-tilstand, slik de
+temporale tabellene ellers i modellen har.
+
+Å slette raden er ikke et alternativ: tildelinger, delegeringstak og nekt refererer koden, og
+historikken skal bestå. «Ta ut av bruk» i kravet forutsetter derfor en liten modellutvidelse, og
+semantikken bør være den samme som ellers: raden blir stående, den merkes som noe som ikke skal tas
+i bruk på nytt, og det som allerede er tildelt berøres ikke av merkingen alene. Hvilken form
+markøren skal ha — en gyldighetsperiode på linje med de temporale tabellene, eller et enklere flagg
+— er en modellbeslutning som hører sammen med denne leveransen.
+
+## Hvorfor et API her, når andre deler av modellen forvaltes i kildekoden
+
+Flere av mekanismene rundt katalogen forvaltes bevisst gjennom migreringer, uten flate. Skillet
+følger konsekvensen av en endring, ikke hvor krevende den er å bygge:
+
+- Å **åpne data** eller å legge noe i **gulvet** endrer hvem som kan se hvilke data, uten at noen
+  er tildelt noe. Der er fravær av en skriveflate en egenskap.
+- Å **innføre en tilgang i katalogen** endrer ingens tilgang. Den blir først virksom gjennom en
+  tildeling, som har sine egne rettigheter og sin egen sporing.
+
+Katalogen er dessuten den mekanismen som har et løpende dokumentasjonsbehov, og det behovet kan
+ikke dekkes av migreringer uten å gjøre hver tekstrettelse til en kodeendring.
+
+## Åpne designspørsmål
+
+- [ ] Skal dokumentasjonsrettigheten kunne avgrenses til et navnerom eller et fagområde, eller
+      gjelder den hele katalogen?
+- [ ] Skal en beskrivelsesendring kunne foreslås og godkjennes, eller er rettigheten i seg selv
+      godkjenningen? Sporingen viser uansett hvem som endret hva og når.
+- [ ] Skal implikasjoner mellom tilganger — hvilke tilganger en tilgang omfatter — også kunne
+      forvaltes gjennom API-et? Kravene her dekker tilgangene selv, ikke hvordan de henger sammen,
+      og implikasjoner er den delen som faktisk endrer rekkevidde.
+- [ ] Hvilken form skal markøren for «ute av bruk» ha, og skal den hindre nye tildelinger av
+      tilgangen eller bare varsle om dem?
+- [ ] Skal listespørringen kunne filtrere på «mangler beskrivelse», eller er det en klientoppgave?

krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.feature

@@ -0,0 +1,131 @@
+# language: no
+@BRU-TIL-KAT-001 @must @planned
+Egenskap: Forvalte tilgangskatalogen gjennom API
+  Som utvikler hos Sikt
+  ønsker jeg å opprette, endre og ta ut av bruk tilganger i tilgangskatalogen gjennom API
+  slik at katalogen kan forvaltes som en del av løsningen, og ikke bare direkte i databasen.
+
+  Tilgangskatalogen er listen over tilgangene som finnes: koden hver av dem identifiseres ved,
+  og beskrivelsen av hva den gir. Alt annet i tilgangsstyringen peker på den — en tildeling, et
+  delegeringstak og et nekt navngir en tilgang fra katalogen — så katalogen er både den mest
+  leste og den mest inngripende listen i modellen. En ny tilgang der er ikke i seg selv en
+  tilgang noen har fått; den er et begrep resten av modellen kan referere til.
+
+  Katalogen forvaltes i dag av databaseforvaltningen. Denne egenskapen gir den et API med to
+  nivåer: utviklere hos Sikt kan opprette, endre og ta en tilgang ut av bruk, mens det finnes en
+  egen rettighet for dem som bare skal skrive beskrivelser, jf. BRU-TIL-KAT-002. Skillet er
+  hensikten med kravet: dokumentasjonen av en tilgang bør kunne forbedres av dem som kan
+  fagområdet, uten at de samtidig kan endre hva tilgangen er.
+
+  # ÅPNE SPØRSMÅL:
+  # - Skal implikasjoner mellom tilganger og navnerom for tilganger også forvaltes gjennom
+  #   API-et, eller forblir de en beslutning i kildekoden? Denne egenskapen dekker tilgangene
+  #   selv, ikke hvordan de henger sammen.
+  # - Skal listingen kunne avgrenses per navnerom, eller er hele katalogen alltid ett svar?
+
+  Bakgrunn:
+    Gitt jeg er innlogget i løsningen
+
+  Regel: Hele tilgangskatalogen kan listes
+
+    # Behovet som mangler i dag: ingen av inngangene til katalogen viser den i sin helhet. De
+    # eksisterende listene er avledet av noe annet — tilgangene en applikasjon har, tilgangene
+    # jeg selv har, tilgangene jeg kan tildele — og en tilgang uten en eneste tildeling er
+    # dermed usynlig i løsningen, selv om den finnes. Både den som forvalter katalogen og den
+    # som dokumenterer den trenger å se den som en liste.
+
+    Scenario: Liste hele katalogen
+      Når jeg åpner tilgangskatalogen
+      Så ser jeg alle tilgangene som finnes
+      Og hvert innslag viser tilgangskoden og beskrivelsen
+
+    Scenario: Tilganger uten tildelinger er med i listen
+      Gitt en tilgang finnes i katalogen uten å være tildelt noen
+      Når jeg åpner tilgangskatalogen
+      Så er tilgangen med i listen
+
+    Scenario: Listen er paginert
+      Gitt katalogen har flere tilganger enn det som vises om gangen
+      Når jeg åpner tilgangskatalogen
+      Så får jeg en avgrenset mengde innslag om gangen
+      Og jeg kan hente de neste innslagene
+
+    Scenario: Listen er sortert forutsigbart
+      Når jeg åpner tilgangskatalogen
+      Så er listen sortert etter tilgangskode i stigende rekkefølge
+
+    Scenario: Listen er lesbar for alle som skal forvalte eller dokumentere katalogen
+      Gitt jeg har rettighet til å oppdatere beskrivelser i katalogen
+      Når jeg åpner tilgangskatalogen
+      Så ser jeg alle tilgangene som finnes
+
+    Scenario: Det fremgår hvilke tilganger som er tatt ut av bruk
+      Gitt en tilgang er tatt ut av bruk
+      Når jeg åpner tilgangskatalogen
+      Så fremgår det at tilgangen ikke lenger skal tas i bruk
+      Og jeg kan velge å se bare tilgangene som er i bruk
+
+  Regel: Bare utviklere hos Sikt kan opprette, endre eller ta ut av bruk en tilgang
+
+    Scenario: Utvikler oppretter en ny tilgang
+      Gitt jeg har utviklerrettighet for tilgangskatalogen
+      Når jeg oppretter en tilgang med en kode og en beskrivelse
+      Så finnes tilgangen i katalogen
+      Og den kan tildeles på lik linje med de øvrige tilgangene
+
+    Scenario: Utvikler endrer en tilgang
+      Gitt jeg har utviklerrettighet for tilgangskatalogen
+      Og en tilgang finnes i katalogen
+      Når jeg endrer beskrivelsen av tilgangen
+      Så er den nye beskrivelsen lagret
+
+    Scenario: Utvikler tar en tilgang ut av bruk
+      Gitt jeg har utviklerrettighet for tilgangskatalogen
+      Og en tilgang finnes i katalogen
+      Når jeg tar tilgangen ut av bruk
+      Så fremgår det i katalogen at tilgangen ikke lenger skal tas i bruk
+      Og tilgangen er ikke slettet
+
+    Scenario: Uten utviklerrettighet avvises opprettelse
+      Gitt jeg ikke har utviklerrettighet for tilgangskatalogen
+      Når jeg forsøker å opprette en tilgang
+      Så avvises endringen
+      Og det fremgår hvilken rettighet som kreves
+
+    Scenario: Uten utviklerrettighet vises ingen handlinger for å endre katalogen
+      Gitt jeg ikke har utviklerrettighet for tilgangskatalogen
+      Når jeg åpner tilgangskatalogen
+      Så ser jeg listen over tilganger
+      Men jeg ser ingen handling for å opprette eller ta en tilgang ut av bruk
+
+  Regel: Koden identifiserer tilgangen og settes én gang
+
+    Scenario: Koden kan ikke endres etter opprettelse
+      Gitt en tilgang finnes i katalogen
+      Når jeg forsøker å endre koden til tilgangen
+      Så avvises endringen
+      Og det fremgår at koden identifiserer tilgangen og ikke kan endres
+
+    Scenario: Opprettelse avvises når koden allerede er i bruk
+      Gitt en tilgang med en gitt kode finnes i katalogen
+      Når jeg forsøker å opprette en ny tilgang med den samme koden
+      Så avvises opprettelsen
+      Og det fremgår at koden allerede er i bruk
+
+    Scenario: En tilgang som er i bruk kan ikke slettes
+      Gitt en tilgang er tildelt noen
+      Når jeg forsøker å fjerne tilgangen fra katalogen
+      Så avvises fjerningen
+      Og det fremgår at tilgangen kan tas ut av bruk i stedet
+
+  Regel: Endringer i katalogen er sporbare
+
+    Scenario: Se hvem som opprettet en tilgang
+      Gitt en tilgang finnes i katalogen
+      Når jeg åpner tilgangen
+      Så ser jeg tidspunktet den ble opprettet og hvem som opprettet den
+
+    Scenario: Se siste endring av en tilgang
+      Gitt en tilgang i katalogen er endret
+      Når jeg åpner tilgangen
+      Så ser jeg tidspunktet for siste endring og hvem som gjorde den

krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/oppdatere_tilgangsbeskrivelser.feature

@@ -0,0 +1,120 @@
+# language: no
+@BRU-TIL-KAT-002 @must @planned
+Egenskap: Oppdatere beskrivelsen av en tilgang
+  Som bidragsyter til dokumentasjonen av tilgangskatalogen
+  ønsker jeg å oppdatere beskrivelsen av en tilgang
+  slik at det står forklart hva tilgangen faktisk gir, uten at jeg kan endre hva tilgangen er.
+
+  Beskrivelsen er det eneste i katalogen som er ren dokumentasjon. Koden identifiserer tilgangen,
+  og alt annet i tilgangsstyringen peker på den; beskrivelsen forklarer den. Derfor er det den
+  ene delen av katalogen som kan forvaltes av flere enn dem som forvalter selve modellen — den
+  som kan fagområdet skal kunne forbedre forklaringen uten å kunne røre begrepet.
+
+  Rettigheten gir derfor tilgang til ett felt, ikke til katalogen. Avgrensningen er et krav til
+  håndhevingen, ikke bare til hvordan flaten ser ut: et forsøk på å endre noe annet skal avvises
+  uansett hvilken vei det kommer inn, også når det følger med i den samme forespørselen som en
+  gyldig beskrivelsesendring.
+
+  Å endre en beskrivelse endrer ingenting for dem som har tilgangen. Det er nettopp derfor
+  rettigheten kan være videre enn utviklerrettigheten i BRU-TIL-KAT-001.
+
+  # ÅPNE SPØRSMÅL:
+  # - Skal rettigheten kunne avgrenses til et fagområde eller et navnerom, eller gjelder den
+  #   hele katalogen?
+  # - Skal en beskrivelsesendring kunne foreslås av flere og godkjennes av noen, eller er
+  #   rettigheten i seg selv godkjenningen?
+
+  Bakgrunn:
+    Gitt jeg er innlogget i løsningen
+    Og jeg har rettighet til å oppdatere beskrivelser i tilgangskatalogen
+
+  Regel: Rettigheten gir rett til å oppdatere beskrivelsen
+
+    Scenario: Oppdatere beskrivelsen av en tilgang
+      Gitt en tilgang finnes i katalogen
+      Når jeg oppdaterer beskrivelsen av tilgangen
+      Så er den nye beskrivelsen lagret
+      Og den vises der tilgangen er nevnt
+
+    Scenario: Beskrivelsen kan tømmes
+      Gitt en tilgang har en beskrivelse
+      Når jeg fjerner beskrivelsen
+      Så står tilgangen uten beskrivelse
+      Og tilgangen finnes fortsatt i katalogen
+
+    Scenario: Finne tilgangen som skal dokumenteres
+      Gitt katalogen har tilganger uten beskrivelse
+      Når jeg åpner tilgangskatalogen
+      Så ser jeg alle tilgangene som finnes, også de uten tildelinger
+      Og jeg kan se hvilke som mangler beskrivelse
+
+    Scenario: Endringen er sporbar
+      Gitt jeg har oppdatert beskrivelsen av en tilgang
+      Når jeg åpner tilgangen
+      Så ser jeg tidspunktet for endringen og hvem som gjorde den
+
+  Regel: Rettigheten gir ikke rett til noe annet enn beskrivelsen
+
+    # Avgrensningen er et håndhevingskrav. Den skal ligge i API-et og i datalaget, ikke bare i
+    # hvilke felter en flate viser: en klient som sender inn mer enn en beskrivelse skal få det
+    # avvist, uansett hvilken inngang den bruker.
+
+    Scenario: Forsøk på å endre tilgangskoden avvises
+      Gitt en tilgang finnes i katalogen
+      Når jeg forsøker å endre koden til tilgangen
+      Så avvises endringen
+      Og det fremgår at rettigheten bare omfatter beskrivelsen
+
+    Scenario: Forsøk på å opprette en tilgang avvises
+      Når jeg forsøker å opprette en ny tilgang i katalogen
+      Så avvises opprettelsen
+      Og det fremgår at rettigheten bare omfatter beskrivelsen
+
+    Scenario: Forsøk på å ta en tilgang ut av bruk avvises
+      Gitt en tilgang finnes i katalogen
+      Når jeg forsøker å ta tilgangen ut av bruk
+      Så avvises endringen
+
+    Scenario: Forsøk på å endre hvilke tilganger en tilgang omfatter avvises
+      Gitt en tilgang omfatter andre tilganger
+      Når jeg forsøker å endre hvilke tilganger den omfatter
+      Så avvises endringen
+
+    Scenario: Forsøk på å endre hvilket navnerom en tilgang hører til avvises
+      Gitt en tilgang hører til et navnerom
+      Når jeg forsøker å flytte tilgangen til et annet navnerom
+      Så avvises endringen
+
+    Scenario: Forsøk på å tildele eller fjerne en tilgang avvises
+      Gitt en tilgang finnes i katalogen
+      Når jeg forsøker å tildele tilgangen til noen
+      Så avvises tildelingen
+      Og det fremgår at rettigheten ikke omfatter tildeling
+
+    Scenario: En forespørsel som endrer mer enn beskrivelsen avvises i sin helhet
+      Gitt en tilgang finnes i katalogen
+      Når jeg sender inn en endring som både oppdaterer beskrivelsen og noe annet
+      Så avvises hele endringen
+      Og beskrivelsen er uendret
+
+    Scenario: Avgrensningen gjelder uansett inngang
+      Gitt jeg bruker API-et direkte i stedet for en flate
+      Når jeg forsøker å endre noe annet enn beskrivelsen
+      Så avvises endringen på samme måte
+
+  Regel: En beskrivelsesendring påvirker ingen tilganger
+
+    Scenario: Tildelinger er uendret etter en beskrivelsesendring
+      Gitt en tilgang er tildelt flere applikasjoner og brukere
+      Når jeg oppdaterer beskrivelsen av tilgangen
+      Så har de samme applikasjonene og brukerne den samme tilgangen som før
+
+    Scenario: Ingen mister eller får tilgang til data
+      Gitt en bruker arbeider med en tilgang
+      Når beskrivelsen av tilgangen oppdateres
+      Så er det brukeren kan gjøre uendret
+
+    Scenario: Andre deler av tilgangsmodellen er uberørt
+      Gitt en tilgang er nevnt i et delegeringstak og i et nekt
+      Når jeg oppdaterer beskrivelsen av tilgangen
+      Så er både delegeringstaket og nektet uendret