Merge pull request #320 from minvws/update/docs-oin

updated docs to include OIN instead of URA

Author: fouadsfarijlani

README.md

@@ -226,11 +226,11 @@ To use this system:
     mtls_override_cert=./secrets/self-signed-uzi-server-cert.crt
     ```
  
-2. Insert a new organization via a POST to `/orgs`. The organization ura should be the URA of the uzi certificate you
+2. Insert a new organization via a POST to `/orgs`. The organization OIN should be the serialNumber of the OIN certificate you
 
    will be testing with.
 
-   Note: there is no mTLS check here. You can add multiple organizations with different URA values for testing.
+   Note: there is no mTLS check here. You can add multiple organizations with different OIN values for testing.
 
 3. Next, you will need to register your public key to the key services. You can do this by calling `/register/certificate` with a JSON body like:
 
@@ -286,7 +286,7 @@ To use this system:
       POST /oprf/eval
       {
         "encryptedPersonalId": "EJU9qVhKNmw_UhCXDN_aVM4GL1DCmpDs8QD5WOdUBCU=",
-        "recipientOrganization": "ura:12345678",
+        "recipientOrganization": "oin:00000099000000001000",
         "recipientScope": "nvi"
       }
 
@@ -331,7 +331,7 @@ To use this system:
         },
         "decrypted": {
           "subject": "pseudonym:eval:-Jpsoeik2058ip20b9Wd-vlwpjkjxRN4IoBrk8Ym2Bg=",
-          "aud": "ura:12345678",
+          "aud": "oin:100000099000000001000",
           "scope": "nvi",
           "version": "1.1",
           "iat": 1758616285,

app/application.py

@@ -16,14 +16,13 @@
 from app.config import get_config
 from app.auth import get_auth_ctx
 
-
 API_DESCRIPTION = """
 The Pseudoniemendienst (PRS) lets parties exchange data about a person without
 sharing their BSN. Instead of a BSN, parties exchange **RIDs** and **pseudonyms**
 that are scoped to a recipient organization and scope.
 
-A recipient organization is always identified by a URA in the form
-`ura:<8 digits>` (e.g. `ura:90000036`).
+A recipient organization is always identified by a OIN in the form
+`oin:<20 digits>` (e.g. `oin:00000099000000001000`).
 
 The endpoints are grouped into the sections below. Most sections are protected by
 mutual TLS (mTLS); the calling organization and, where relevant, its public key
@@ -44,7 +43,7 @@
         "name": "Organizational Services",
         "description": (
             "Manage recipient organizations. An organization is identified by its "
-            "URA and has a `max_key_usage` (`bsn`, `rp`, or `irp`) that caps which "
+            "OIN and has a `max_key_usage` (`bsn`, `rp`, or `irp`) that caps which "
             "pseudonym types it is allowed to exchange."
         ),
     },

docs/endpoints.md

@@ -4,7 +4,7 @@ Previously when working with applications within gfmodules, the actual BSN numbe
 
 This document lists the main service endpoints. The testing/helper endpoints (`/test/...`) are documented in [tests.md](tests.md), and the end-to-end OPRF evaluation flow is described in [oprf-eval-flow.md](oprf-eval-flow.md).
 
-A recipient organization is always identified by a URA in the form `ura:<8 digits>` (e.g. `ura:90000036`).
+A recipient organization is always identified by a OIN in the form `oin:<20 digits>` (e.g. `oin:00000099000000001000`).
 
 ## Organizational Services
 
@@ -13,21 +13,21 @@ Create a new organization.
 
 ```json
 {
-  "ura": "90000036",
+  "oin": "00000099000000001000",
   "name": "Example Organization",
   "max_key_usage": "irp"
 }
 ```
 
 `max_key_usage` is one of `bsn`, `rp`, or `irp` and caps which pseudonym types the organization may exchange.
 
-#### `GET /org/{ura}`
-Return the organization for the given URA (digits only, e.g. `90000036`).
+#### `GET /org/{oin}`
+Return the organization for the given OIN (digits only, e.g. `00000099000000001000`).
 
-#### `PUT /org/{ura}`
+#### `PUT /org/{oin}`
 Update an organization's `name` and `max_key_usage`.
 
-#### `DELETE /org/{ura}`
+#### `DELETE /org/{oin}`
 Delete an organization (and its keys).
 
 ## Key Registration Services
@@ -45,7 +45,7 @@ Register the public key (taken from the mTLS client certificate) for one or more
 
 Returns `201` on success, `409` if a key for that organization/scope already exists.
 
-#### `GET /keys/{ura}`
+#### `GET /keys/{oin}`
 List the registered public keys for an organization.
 
 #### `PUT /keys/{key_id}`
@@ -62,7 +62,7 @@ Exchange a personal ID for a pseudonym targeted at a recipient organization/scop
 ```json
 {
   "personalId": "NL:bsn:950000012",
-  "recipientOrganization": "ura:90000036",
+  "recipientOrganization": "oin:00000099000000001000",
   "recipientScope": "bar",
   "pseudonymType": "irreversible"
 }
@@ -76,7 +76,7 @@ Exchange a personal ID for a RID that the recipient can later redeem. The RID is
 ```json
 {
   "personalId": "NL:bsn:950000012",
-  "recipientOrganization": "ura:90000036",
+  "recipientOrganization": "oin:00000099000000001000",
   "recipientScope": "bar",
   "ridUsage": "irp"
 }
@@ -88,7 +88,7 @@ Redeem a previously issued RID for a pseudonym (or the BSN, when allowed). The r
 ```json
 {
   "rid": "rid:<encrypted-rid>",
-  "recipientOrganization": "ura:90000036",
+  "recipientOrganization": "oin:00000099000000001000",
   "recipientScope": "bar",
   "pseudonymType": "irp"
 }
@@ -111,7 +111,7 @@ Evaluate a blinded personal identifier and return a JWE (encrypted to the recipi
 ```json
 {
   "encryptedPersonalId": "co1ZgSqfsiB8iEzmKWl3xgxlc0erstUNyBAC3tdjxzg=",
-  "recipientOrganization": "ura:90000036",
+  "recipientOrganization": "oin:00000099000000001000",
   "recipientScope": "bar"
 }
 ```

docs/hsm-key-cleanup.md

@@ -12,7 +12,7 @@ not yet marked `removed`, the program:
 
 1. Destroys the corresponding key in the HSM via
    `POST {hsm_url}/hsm/{module}/{slot}/destroy` with the key's label
-   (`ura-ura:<ura>-v<version>` — the same label used during evaluation).
+   (`oin-<oin>-v<version>` — the same label used during evaluation).
 2. Marks the version as `removed` in the database.
 
 If the HSM call fails for a version, that version is left untouched so the next

docs/oprf-eval-flow.md

@@ -3,7 +3,7 @@
 This describes the internal PRS flow when a client asks the PRS to evaluate a
 blinded personal identifier. The evaluation can run either against a local OPRF
 key or, in production, against an HSM. When the HSM is used, the active key
-versions are looked up from the `hsm_key_version` table (per URA, for the current
+versions are looked up from the `hsm_key_version` table (per OIN, for the current
 date), the blind is evaluated against **every** active version, and the resulting
 JWE stays backwards compatible: the `subject` always carries the latest version,
 while older versions are added in a separate `extra_versions` claim.
@@ -26,13 +26,13 @@ sequenceDiagram
 
     Client->>Router: POST /oprf/eval<br/>{encryptedPersonalId, recipientOrganization, recipientScope}
 
-    Note over Router: recipientOrganization must start with "ura:"
+    Note over Router: recipientOrganization must start with "oin:"
     alt invalid prefix
         Router-->>Client: 400 Invalid recipient organization
     end
 
-    Router->>Org: get_by_ura(ura)
-    Org->>DB: SELECT organization WHERE ura = ?
+    Router->>Org: get_by_oin(oin)
+    Org->>DB: SELECT organization WHERE oin = ?
     DB-->>Org: organization | none
     alt organization not found
         Org-->>Router: none
@@ -54,11 +54,11 @@ sequenceDiagram
     alt HSM configured (hsm_url set)
         OPRF->>Ver: get_active_versions(now)
         Ver->>DB: SELECT hsm_key_version<br/>not removed, from_dt <= now, until_dt null/>= now
-        DB-->>Ver: active versions (all URAs)
+        DB-->>Ver: active versions (all OINs)
         Ver-->>OPRF: active versions
-        Note over OPRF: filter by URA -> sorted version numbers<br/>(error if none active)
+        Note over OPRF: filter by OIN -> sorted version numbers<br/>(error if none active)
         loop for each active version v
-            OPRF->>HSM: POST /oprf/evaluate<br/>label "ura-<org>-v<v>", blinded_point
+            OPRF->>HSM: POST /oprf/evaluate<br/>label "oin-<org>-v<v>", blinded_point
             HSM-->>OPRF: result (eval bytes for v)
         end
     else local key

docs/tests.md

@@ -25,7 +25,7 @@ Request:
 POST /oprf/eval
 {
   "encryptedPersonalId": "co1ZgSqfsiB8iEzmKWl3xgxlc0erstUNyBAC3tdjxzg=",
-  "recipientOrganization": "ura:90000036",
+  "recipientOrganization": "oin:00000099000000001000",
   "recipientScope": "bar"
 }
 ```
@@ -66,7 +66,7 @@ Response:
     },
     "decrypted": {
       "subject": "pseudonym:eval:Ngb5jRWtUc_EtfPud1uPnjhHwvww1pt51wx_DBao_Uc=",
-      "aud": "ura:90000036",
+      "aud": "oin:00000099000000001000",
       "scope": "bar",
       "version": "1.1",
       "iat": 1762769767,
@@ -94,7 +94,7 @@ Request:
 POST /exchange/pseudonym
 {
   "personalId": "NL:bsn:950000012",
-  "recipientOrganization": "ura:90000036",
+  "recipientOrganization": "oin:00000099000000001000",
   "recipientScope": "bar",
   "pseudonymType": "irreversible"
 }
@@ -151,11 +151,11 @@ Response:
 
 # Scenarios:
 
- org   | ura          | max_key_usage 
--------|--------------|---------------
- Org 1 | ura:90000036 | irp           
- Org 2 | ura:90000037 | rp            
- Org 3 | ura:90000038 | bsn           
+ org   | oin                      | max_key_usage 
+-------|--------------------------|---------------
+ Org 1 | oin:00000099000000001000 | irp           
+ Org 2 | oin:00000098000000001000 | rp            
+ Org 3 | oin:00000097000000001000 | bsn           
 
 * Org 1 can only create irreversible pseudonyms. It cannot be decoded back to the personal ID by anyone.
 * Org 2 can create reversible pseudonyms. It cannot decode itself back to the personal ID but can allow others (who have bsn max_key_usage) to do so.