# USCIS Extends Expiration Date for Permanent Resident Card

This use case concerns the extension of the validity period of a permanent resident card by USCIS.

## Prerequisites

1. Resident has received a digital Permanent Resident Card that resides in their digital wallet.
2. USCIS desires to extend the digital Permanent Resident Card and has had the necessary interactions with the resident in order to do so.

## Steps

1. When the digital PRC credential stored in the wallet expires, user is notified to request for a new credential using secure DID messaging / Wallet notification(???).
2. When the user proceeds with the renewal of PRC Credential, wallet contacts the USCIS IDP for authentication. If the user has an active authenticated session with the USCIS IDP, login screen is bypassed and an access_token to request renewed PRC credential is issued to the wallet. Using this access_token wallet can request for a renewed Digital PRC Credential from the credential endpoint.
1. If there is no active authenticated session with USCIS IDP, the user needs to complete the login step (and any additional 2FA).

## Results

1. An updated digital PRC is stored in the resident's digital wallet.

## Stage 1: Refresh Permanent Resident Card

The digital extension process is started when the digital wallet detects that the digital PRC needs to be refreshed and initiates the refresh process.

sequenceDiagram
    participant H as Holder
    participant WA as Wallet APP
    participant CP as Credential Provider (A part of the Issuer Web Service)
    participant CGS as Credential Generation service (A part of the Issuer Web Service)
    participant CI as IDP
    participant AS as USCIS Authorization Server
    participant PRC as PRC Data Interface 
    autonumber
    note over  H,WA: If the wallet application currently has an <br/> active access token, authentication  with<br/> IDP is not needed for token refresh
 
    WA ->> WA: Generates DID for cryptographic binding of the credential and prepares proof of possession <br/> of private key authorized via the public key listed in the DID document
    note left of WA: This can be same DID or new DID. We suggest using new DID due to privacy reasons.
    
    par Wallet requests copy of credential using the access token (This request can be repeated as long as the access token is valid)
        WA ->> CP: Request renewed PRC Credential (using access_token to prove authorization)
        CP ->> CP: Validate Credential Request including the proof of possession against the supplied DID
        CP ->> AS: Request for client access_token to call PRC Data interface
        AS ->> CP: After success client authentication, returns client access_token
        CP ->> PRC: Query for a record matching sub and AIID combo (???) from access_token
        PRC ->> CP: Query Response (containing PRC user claims)
        CP -->> CGS: Generate PRC Credential request (using claims retreived from PRC database)
        CGS -->> CP: Generate PRC Credential
        CP ->> WA: "Issued Credential" 
    end

<details>
<summary> PRC Credential Refresh via Credential Endpoint - Protocol Details</summary>

## PRC Credential Refresh via Credential Endpoint

- Pre-requisites:
- User completes Authentication with USCIS IDP / Has an active authenticated session with USCIS IDP and an Access Token to call credential endpoint is obtained

- At Step 2, Using the access_token obtained in the previous step, the wallet requests for a new PRC credential via Credential Endpoint.

    
POST /credential HTTP/1.1
Host: prc-issuer.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW

type=prc
format=ldp%5Fvc
did=did%3Aexample%3Aebfeb1f712ebc6f1c276e12ec21
proof=%7B%22type%22:%22...-ace0-9c5210e16c32%22%7D
        

- At Step 4, the client requests USCIS authorization server for client access_token to call PRC Data interface.

POST /token HTTP/1.1
Authorization: Basic YjY4Y2I2ZDctNGI5Yi00ODdkLThkZjktM2RkNzg4ZmYyZGEzOm5jalFDYjFJZkhTLW1UT nYuVDBycXVNdzBK
grant_type=client_credentials&scope=subject_data

- At Step 5, After successfull authentication, the authorization servers responds with the access_token.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache 

{
    "access_token": "BH9OOtzzxsy8MPvqWlvbCV1GV4UfKrytlloW4YSOD..",
    "expires_in": 3599,
    "scope": "subject_data",
    "token_type": "bearer"
}

- At Step 6, Query the PRC User data endpoint for the record matching the sub.

        
GET /1.0/subjects/data?aiid=FiIJethCqaTkWh70Gq8D&subjectReference=39874.K ENRBSUZ&holderDid=did:example:1234
Host: api.prc.example.com
Authorization: Bearer BH9OOtzzxsy8MPvqWlvbCV1GV4UfKrytlloW4YSODEU.
Content-Type: application/json
        

- At Step 7, Query response is returned from the PRC User data endpoint.

        
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache       

{
    "subjectData": {
        "did":"did:example:1234"
        "image": "data:image/png;base64,iVBOR....=",
        "lprNumber": "1958-08-17",
        "gender": "Male",
        "residentSince": "2015-01-01",
        "givenName": "Louis",
        "familyName": "Pasteur",
        "birthCountry": "France",
        "commuterClassification": "C1",
        "birthDate": "1958-08-17",
        "lprCategory": "C09"
    }
}
        

- At Step 8, The credential endpoint (after completing necessary background process) returns the renewed PRC credential in the requested format.

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache

{
  "format": "ldp_vc"
  "credential" : "LUpixVCWJk0eOt4CXQe1NXK....WZwmhmn9OQp6YxX0a2L"
}
    

</details>