### Install Development Dependencies

Source: https://github.com/openid/sharedsignals/blob/main/README.md

This section details the necessary steps to install the tools required for developing and generating specification files. It involves installing 'xml2rfc' using pip and 'kramdown-rfc' using Ruby gems.

```shell
pip install xml2rfc
gem install kramdown-rfc
```

--------------------------------

### HTTP GET Request to Read All Stream Configurations

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

An example HTTP GET request to retrieve configurations for all available Event Streams when the 'stream_id' parameter is omitted. This request includes Host and Authorization headers.

```http
GET /ssf/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
```

--------------------------------

### GET /.well-known/ssf-configuration

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

Retrieves the Transmitter Configuration Metadata document required for signal sharing setup.

```APIDOC
## GET /.well-known/ssf-configuration

### Description
Retrieves the JSON configuration document for an SSF Transmitter. This discovery endpoint allows Receivers to obtain necessary metadata, including authorization schemes and supported protocols.

### Method
GET

### Endpoint
/.well-known/ssf-configuration

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
GET /.well-known/ssf-configuration HTTP/1.1
Host: tr.example.com

### Response
#### Success Response (200)
- **spec_urn** (string) - A URN describing the protocol specification used for authorization.

#### Response Example
{
  "spec_urn": "urn:ietf:rfc:6749"
}
```

--------------------------------

### Transmitter Configuration Response Example

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

An example of a successful HTTP 200 OK response from a Transmitter, containing configuration metadata such as issuer, JWKS URI, and various management endpoints.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "spec_version": "1_0",
  "issuer": "https://tr.example.com",
  "jwks_uri": "https://tr.example.com/jwks.json",
  "delivery_methods_supported": [
    "urn:ietf:rfc:8935",
    "urn:ietf:rfc:8936"],
  "configuration_endpoint": "https://tr.example.com/ssf/mgmt/stream",
  "status_endpoint": "https://tr.example.com/ssf/mgmt/status",
  "add_subject_endpoint": "https://tr.example.com/ssf/mgmt/subject:add",
  "remove_subject_endpoint": "https://tr.example.com/ssf/mgmt/subject:remove",
  "verification_endpoint": "https://tr.example.com/ssf/mgmt/verification",
  "critical_subject_members": ["tenant", "user"],
  "authorization_schemes": [
      {
        "spec_urn": "urn:ietf:rfc:6749"
      },
      {
        "spec_urn": "urn:ietf:rfc:8705"
      }
    ],
  "default_subjects": "NONE"
}
```

--------------------------------

### Example: Administrative Reason Information (JSON)

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

Demonstrates the structure of the 'reason_admin' claim, which provides localizable administrative messages for logging and auditing. It includes examples with BCP47 language tags for English, German, and Spanish.

```json
{
    "reason_admin": {
        "en": "Landspeed Policy Violation: C076E82F",
        "de": "Landspeed-Richtlinienverstoß: C076E82F",
        "es-410": "Violación de la política de landspeed: C076E82F"
    }
}
```

--------------------------------

### Example: User Reason Information (JSON)

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

Illustrates the 'reason_user' claim, designed to convey localizable, user-friendly messages for end-users. The example shows messages in English, German, and Spanish, using BCP47 language tags.

```json
{
    "reason_user": {
        "en": "Access attempt from multiple regions.",
        "de": "Zugriffsversuch aus mehreren Regionen.",
        "es-410": "Intento de acceso desde varias regiones."
    }
}
```

--------------------------------

### Example Transmitter Configuration Metadata (JSON)

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

This JSON object demonstrates an example of Transmitter configuration metadata, specifically showing the 'spec_version' field. This version identifies the implementer's draft or final specification version.

```json
{
  "spec_version": "1_0"
}
```

--------------------------------

### HTTP GET Request to Read Stream Configuration

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

An example HTTP GET request to retrieve the configuration for a specific Event Stream. It includes the necessary Host and Authorization headers. The 'stream_id' query parameter is used to identify the target stream.

```http
GET /ssf/stream?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
```

--------------------------------

### Token Claims Change Event Examples

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

Examples of the token claims change event payload, demonstrating different scenarios and claim inclusions.

```APIDOC
## Token Claims Change Event Examples

### Description
This section provides examples of the token claims change event payload. These examples illustrate the structure and required/optional claims for different scenarios, including OIDC ID Token claims changes and SAML Assertion claims changes.

### Request Example (OIDC ID Token Claims Change - Required Claims Only)
```json
{
    "iss": "https://idp.example.com/987654321/",
    "jti": "9afce1e4e642b165fcaacdd0e7aa4903",
    "iat": 1615305159,
    "aud": "https://sp.example2.net/caep",
    "txn": "8675309",
    "sub_id": {
        "format": "jwt_id",
        "iss": "https://idp.example.com/987654321/",
        "jti": "f61t6e20zdo3px56gepu8rzlsp4c1dpc0fx7"
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
            "event_timestamp": 1615304991,
            "claims": {
                "role": "ro-admin"
            }
        }
    }
}
```

### Request Example (OIDC ID Token Claims Change - Optional Claims)
```json
{
    "iss": "https://idp.example.com/987654321/",
    "jti": "9afce1e4e642b165fcaacdd0e7aa4903",
    "iat": 1615305159,
    "aud": "https://sp.example2.net/caep",
    "txn": "8675309",
    "sub_id": {
        "format": "jwt_id",
        "iss": "https://idp.example.com/987654321/",
        "jti": "f61t6e20zdo3px56gepu8rzlsp4c1dpc0fx7"
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
            "event_timestamp": 1615304991,
            "initiating_entity": "policy",
            "reason_admin": {
                "en": "User left trusted network: CorpNet3"
            },
            "reason_user": {
                "en": "You're no longer connected to a trusted network.",
                "it": "Non sei più connesso a una rete attendibile."
            },
            "claims": {
                "trusted_network": false
            }
        }
    }
}
```

### Request Example (SAML Assertion Claims Change - Required Claims Only)
```json
{
    "iss": "https://idp.example.com/987654321/",
    "jti": "dae94fed5f459881efa38b65c6772ddc",
    "iat": 1615305159,
    "aud": "https://sp.example2.net/caep",
    "txn": "8675309",
    "sub_id": {
        "format": "saml_assertion_id",
        "issuer": "https://idp.example.com/987654321/",
        "assertion_id": "_a75adf55-01d7-dbd8372ebdfc"
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
            "event_timestamp": 1615304991,
            "claims": {
                "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role": "ro-admin"
            }
        }
    }
}
```
```

--------------------------------

### Device Compliance Change Event Example (JSON)

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

This JSON example details a Device Compliance Change event where a device transitions from 'compliant' to 'not-compliant'. It includes optional claims like 'reason_admin' and 'reason_user' to provide context for the change.

```json
{
    "iss": "https://idp.example.com/123456789/",
    "jti": "24c63fb56e5a2d77a6b512616ca9fa24",
    "iat": 1615305159,
    "aud": "https://sp.example.com/caep",
    "txn": "8675309",
    "sub_id": {
        "format": "complex",
        "device": {
            "format": "iss_sub",
            "iss": "https://idp.example.com/123456789/",
            "sub": "e9297990-14d2-42ec-a4a9-4036db86509a"
        },
        "tenant": {
            "format": "opaque",
            "id": "123456789"
        }
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/device-compliance-change": {
            "current_status": "not-compliant",
            "previous_status": "compliant",
            "initiating_entity": "policy",
            "reason_admin": {
                "en": "Location Policy Violation: C076E8A3"
            },
            "reason_user": {
                "en": "Device is no longer in a trusted location."
            },
            "event_timestamp": 1615304991
        }
    }
}
```

--------------------------------

### Session Established Event Example (JSON)

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

A non-normative example of the 'session-established' event type in JSON format. This event includes optional claims such as user agent fingerprint, authentication context class reference, authentication methods reference, and external session identifier.

```json
{
    "iss": "https://idp.example.com/123456789/",
    "jti": "24c63fb56e5a2d77a6b512616ca9fa24",
    "iat": 1615305159,
    "aud": "https://sp.example.com/caep",
    "txn": "8675309",
    "sub_id": {
      "format": "email",
      "email": "someuser@somedomain.com"
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/session-established": {
          "fp_ua": "abb0b6e7da81a42233f8f2b1a8ddb1b9a4c81611",
          "acr": "AAL2",
          "amr": ["otp"],
          "event_timestamp": 1615304991
        }
    }
}
```

--------------------------------

### Check Event Stream Status Request (HTTP)

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

An example HTTP GET request to query the current status of an Event Stream. It requires a stream_id and includes authorization headers.

```http
GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
```

--------------------------------

### CAEP Device Compliance Change Event Example

Source: https://context7.com/openid/sharedsignals/llms.txt

An example of a Security Event Token (SET) for a CAEP Device Compliance Change event, illustrating a scenario where a device's compliance status has changed.

```APIDOC
## CAEP Device Compliance Change Event

### Description
This example provides a Security Event Token (SET) for a CAEP Device Compliance Change event. It details a scenario where a device's compliance status has shifted, for instance, from compliant to non-compliant, including reasons for the change.

### Event Type
`https://schemas.openid.net/secevent/caep/event-type/device-compliance-change`

### Request Example
```json
{
  "iss": "https://idp.example.com/123456789/",
  "jti": "24c63fb56e5a2d77a6b512616ca9fa24",
  "iat": 1615305159,
  "aud": "https://sp.example.com/caep",
  "txn": "8675309",
  "sub_id": {
    "format": "complex",
    "device": {
      "format": "iss_sub",
      "iss": "https://idp.example.com/123456789/",
      "sub": "e9297990-14d2-42ec-a4a9-4036db86509a"
    },
    "tenant": {
      "format": "opaque",
      "id": "123456789"
    }
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/device-compliance-change": {
      "current_status": "not-compliant",
      "previous_status": "compliant",
      "initiating_entity": "policy",
      "reason_admin": {
        "en": "Location Policy Violation: C076E8A3"
      },
      "reason_user": {
        "en": "Device is no longer in a trusted location."
      },
      "event_timestamp": 1615304991
    }
  }
}
```
```

--------------------------------

### Example: SET Containing a CAEP Event with Properties

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

Illustrates a CAEP event token-claims-change, demonstrating how to pass specific claim properties within the event payload.

```json
{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "email",
    "email": "user@example.com"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
      "claims": {
        "token": "some-token-value"
      }
    }
  }
}
```

--------------------------------

### Session Presented Event Example (JSON)

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

A non-normative example of the 'session-presented' event type in JSON format. This event signifies that the Transmitter has observed the session to be present and includes optional claims like user agent fingerprint and external session identifier.

```json
{
    "iss": "https://idp.example.com/123456789/",
    "jti": "24c63fb56e5a2d77a6b512616ca9fa24",
    "iat": 1615305159,
    "aud": "https://sp.example.com/caep",
    "txn": "8675309",
    "sub_id": {
      "format": "email",
      "email": "someuser@somedomain.com"
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/session-presented": {
          "fp_ua": "abb0b6e7da81a42233f8f2b1a8ddb1b9a4c81611",
          "ext_id": "12345",
          "event_timestamp": 1615304991
        }
    }
}
```

--------------------------------

### Example: SET Containing an SSF Event with a Simple Subject and a Property Member

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

Demonstrates a CAEP event with a simple subject identifier and additional event-specific properties.

```json
{
  "iss": "https://sp.example2.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "email",
    "email": "foo@example2.com"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
      "event_timestamp": 1600975810,
      "claims": {
         "role": "ro-admin"
      }
    }
  }
}
```

--------------------------------

### RISC Credential Compromise Event Example (JSON)

Source: https://context7.com/openid/sharedsignals/llms.txt

An example of a Security Event Token (SET) used to signal that a user's credential has been found to be compromised, including the type of credential and the reason.

```json
{
  "iss": "https://idp.example.com/3456790/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1508184845,
  "aud": "https://sp.example2.net/caep",
  "sub_id": {
    "format": "iss_sub",
    "iss": "https://idp.example.com/3456790/",
    "sub": "joe.smith@example.com"
  },
  "events": {
    "https://schemas.openid.net/secevent/risc/event-type/credential-compromise": {
      "credential_type": "password",
      "event_timestamp": 1508184800,
      "reason_admin": {
        "en": "Password found in known breach database"
      }
    }
  }
}
```

--------------------------------

### CAEP Credential Change Event Example

Source: https://context7.com/openid/sharedsignals/llms.txt

An example of a Security Event Token (SET) for a CAEP Credential Change event, illustrating scenarios like credential creation, modification, or revocation.

```APIDOC
## CAEP Credential Change Event

### Description
This example showcases a Security Event Token (SET) for a CAEP Credential Change event. It covers various credential lifecycle events such as creation, modification, or revocation, using a FIDO2 authenticator provisioning scenario.

### Event Type
`https://schemas.openid.net/secevent/caep/event-type/credential-change`

### Request Example
```json
{
  "iss": "https://idp.example.com/3456789/",
  "jti": "07efd930f0977e4fcc1149a733ce7f78",
  "iat": 1615305159,
  "aud": "https://sp.example2.net/caep",
  "txn": "8675309",
  "sub_id": {
    "format": "iss_sub",
    "iss": "https://idp.example.com/3456789/",
    "sub": "jane.smith@example.com"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/credential-change": {
      "credential_type": "fido2-roaming",
      "change_type": "create",
      "fido2_aaguid": "accced6a-63f5-490a-9eea-e59bc1896cfc",
      "friendly_name": "Jane's USB authenticator",
      "initiating_entity": "user",
      "reason_admin": {
        "en": "User self-enrollment"
      },
      "event_timestamp": 1615304991
    }
  }
}
```
```

--------------------------------

### Example: SET Containing an SSF Event with a Complex Subject Member

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

Provides an example of a complex subject identifier containing both user and device information, used for a session-revoked event.

```json
{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "complex",
    "user": {
      "format": "iss_sub",
      "iss": "https://idp.example.com/3957ea72-1b66-44d6-a044-d805712b9288/",
      "sub": "jane.smith@example.com"
    },
    "device": {
      "format": "iss_sub",
      "iss": "https://idp.example.com/3957ea72-1b66-44d6-a044-d805712b9288/",
      "sub": "e9297990-14d2-42ec-a4a9-4036db86509a"
    }
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked": {
      "initiating_entity": "policy",
      "reason_admin": {
        "en": "Policy Violation: C076E82F"
      },
      "reason_user": {
        "en": "Land speed violation.",
        "es": "Violación de velocidad en tierra."
      },
      "event_timestamp": 1600975810
    }
  }
}
```

--------------------------------

### Custom Assurance Level Change Event Example (JSON)

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

This JSON example illustrates a custom Assurance Level Change event, where the levels are defined by a custom namespace ('Retinal Scan'). It showcases flexibility in defining assurance levels beyond standard ones.

```json
{
    "iss": "https://idp.example.com/3456789/",
    "jti": "07efd930f0977e4fcc1149a733ce7f78",
    "iat": 1615305159,
    "aud": "https://sp.example2.net/caep",
    "txn": "8675309",
    "sub_id": {
        "format": "iss_sub",
        "iss": "https://idp.example.com/3456789/",
        "sub": "jane.smith@example.com"
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/assurance-level-change": {
            "namespace": "Retinal Scan",
            "current_level": "hi-res-scan",
            "initiating_entity": "user",
            "event_timestamp": 1615304991
        }
    }
}
```

--------------------------------

### Subject Identifier Formats Examples (JSON)

Source: https://context7.com/openid/sharedsignals/llms.txt

Provides examples of various subject identifier formats supported by SSF for referencing principals in events, including email, iss_sub, jwt_id, complex, and IP addresses.

```json
{
  "sub_id": {
    "format": "email",
    "email": "user@example.com"
  }
}
```

```json
{
  "sub_id": {
    "format": "iss_sub",
    "iss": "https://idp.example.com/",
    "sub": "user-unique-id-12345"
  }
}
```

```json
{
  "sub_id": {
    "format": "jwt_id",
    "iss": "https://idp.example.com/123456789/",
    "jti": "B70BA622-9515-4353-A866-823539EECBC8"
  }
}
```

```json
{
  "sub_id": {
    "format": "complex",
    "user": {
      "format": "email",
      "email": "user@example.com"
    },
    "device": {
      "format": "iss_sub",
      "iss": "https://idp.example.com/",
      "sub": "device-uuid-12345"
    },
    "tenant": {
      "format": "opaque",
      "id": "tenant-abc123"
    }
  }
}
```

```json
{
  "sub_id": {
    "format": "ip-addresses",
    "ip-addresses": ["10.29.37.75", "2001:0db8:0000:0000:0000:8a2e:0370:7334"]
  }
}
```

--------------------------------

### Assurance Level Change Event Example (JSON)

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

This JSON example demonstrates an Assurance Level Change event, showing an increase in the assurance level from 'nist-aal1' to 'nist-aal2'. It includes details about the issuer, subject, and event specifics.

```json
{
    "iss": "https://idp.example.com/3456789/",
    "jti": "07efd930f0977e4fcc1149a733ce7f78",
    "iat": 1615305159,
    "aud": "https://sp.example2.net/caep",
    "txn": "8675309",
    "sub_id": {
        "format": "iss_sub",
        "iss": "https://idp.example.com/3456789/",
        "sub": "jane.smith@example.com"
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/assurance-level-change": {
            "namespace": "NIST-AAL",
            "current_level": "nist-aal2",
            "previous_level": "nist-aal1",
            "change_direction": "increase",
            "initiating_entity": "user",
            "event_timestamp": 1615304991
        }
    }
}
```

--------------------------------

### Session Established Event

Source: https://github.com/openid/sharedsignals/blob/main/openid-caep-1_0.md

Details the 'session-established' event, including its optional claims and an example payload.

```APIDOC
## Session Established Event

### Description
This event signifies that a session has been established. It may include optional claims related to the user agent's fingerprint, authentication context, authentication methods, and external session identifiers.

### Event Type URI
`https://schemas.openid.net/secevent/caep/event-type/session-established`

### Event Specific Claims

- **fp_ua** (string) - Optional - Fingerprint of the user agent computed by the Transmitter.
- **acr** (string) - Optional - The authentication context class reference of the session.
- **amr** (array of strings) - Optional - The authentication methods reference of the session.
- **ext_id** (string) - Optional - The external session identifier.

### Request Example
```json
{
    "iss": "https://idp.example.com/123456789/",
    "jti": "24c63fb56e5a2d77a6b512616ca9fa24",
    "iat": 1615305159,
    "aud": "https://sp.example.com/caep",
    "txn": "8675309",
    "sub_id": {
      "format": "email",
      "email": "someuser@somedomain.com"
    },
    "events": {
        "https://schemas.openid.net/secevent/caep/event-type/session-established": {
          "fp_ua": "abb0b6e7da81a42233f8f2b1a8ddb1b9a4c81611",
          "acr": "AAL2",
          "amr": ["otp"],
          "event_timestamp": 1615304991
        }
    }
}
```
```

--------------------------------

### GET /.well-known/ssf-configuration

Source: https://context7.com/openid/sharedsignals/llms.txt

Retrieves the transmitter's configuration, including supported delivery methods, JWKS URI, and various management endpoints.

```APIDOC
## GET /.well-known/ssf-configuration

### Description
Retrieves the transmitter's configuration, including supported delivery methods, JWKS URI, and various management endpoints.

### Method
GET

### Endpoint
/.well-known/ssf-configuration

### Response
#### Success Response (200)
- **spec_version** (string) - The version of the SSF specification.
- **issuer** (string) - The issuer URL of the transmitter.
- **jwks_uri** (string) - The URI for the transmitter's JSON Web Key Set.
- **delivery_methods_supported** (array) - List of supported delivery methods.

#### Response Example
{
  "spec_version": "1_0",
  "issuer": "https://tr.example.com",
  "jwks_uri": "https://tr.example.com/jwks.json",
  "delivery_methods_supported": ["urn:ietf:rfc:8935", "urn:ietf:rfc:8936"]
}
```

--------------------------------

### Retrieve Transmitter Configuration Metadata

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

HTTP GET requests used to discover configuration metadata from a transmitter. Includes examples for standard issuers, issuers with path components, and legacy RISC endpoints.

```http
GET /.well-known/ssf-configuration HTTP/1.1
Host: tr.example.com
```

```http
GET /.well-known/ssf-configuration/issuer1 HTTP/1.1
Host: tr.example.com
```

```http
GET /.well-known/risc-configuration HTTP/1.1
Host: risc-tr.example.com
```

--------------------------------

### Generate Specification Files with Make

Source: https://github.com/openid/sharedsignals/blob/main/README.md

This snippet demonstrates how to generate HTML and TXT versions of specification files using the 'make' command. It requires 'xml2rfc' and 'kramdown-rfc' to be installed. The process involves updating an XML file and then running 'make' with the target file name.

```shell
make foo.html
make foo.txt
```

--------------------------------

### CAEP Session Revoked Event Example

Source: https://context7.com/openid/sharedsignals/llms.txt

An example of a Security Event Token (SET) representing a CAEP Session Revoked event, indicating that a session has been terminated.

```APIDOC
## CAEP Session Revoked Event

### Description
This example demonstrates a Security Event Token (SET) for a CAEP Session Revoked event, which signals the termination of a session. It includes complex subject identification involving user, device, and tenant.

### Event Type
`https://schemas.openid.net/secevent/caep/event-type/session-revoked`

### Request Example
```json
{
  "iss": "https://idp.example.com/123456789/",
  "jti": "24c63fb56e5a2d77a6b512616ca9fa24",
  "iat": 1615305159,
  "aud": "https://sp.example.com/caep",
  "txn": "8675309",
  "sub_id": {
    "format": "complex",
    "user": {
      "format": "iss_sub",
      "iss": "https://idp.example.com/123456789/",
      "sub": "jane.smith@example.com"
    },
    "device": {
      "format": "iss_sub",
      "iss": "https://idp.example.com/123456789/",
      "sub": "e9297990-14d2-42ec-a4a9-4036db86509a"
    },
    "tenant": {
      "format": "opaque",
      "id": "123456789"
    }
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked": {
      "initiating_entity": "policy",
      "reason_admin": {
        "en": "Policy Violation: C076E822"
      },
      "reason_user": {
        "en": "This device is no longer compliant.",
        "it": "Questo dispositivo non è più conforme."
      },
      "event_timestamp": 1615304991
    }
  }
}
```
```

--------------------------------

### HTTP Response for Multiple Stream Configurations

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

An example HTTP 200 OK response containing a JSON array of stream configurations when no 'stream_id' is specified and multiple streams are configured. Each object in the array represents a single stream's configuration.

```json
[
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ]
  },
  {
    "stream_id": "50b2d39934264897902c0581ba7c21a3",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "description": "Stream for Receiver A using events type_2, type_3, type_4"
  }
]
```

--------------------------------

### Example: SET Containing an SSF Event with a Simple Subject Member

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

Demonstrates a basic Security Event Token (SET) using an email-based subject identifier and an account-enabled event.

```json
{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "email",
    "email": "foo@example.com"
  },
  "events": {
    "https://schemas.openid.net/secevent/risc/event-type/account-enabled": {}
  }
}
```

--------------------------------

### RISC Account Disabled Event Example (JSON)

Source: https://context7.com/openid/sharedsignals/llms.txt

Shows the structure of a Security Event Token (SET) indicating that a user's account has been disabled. The event can optionally include a reason for the disablement.

```json
{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1508184845,
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "iss_sub",
    "iss": "https://idp.example.com/",
    "sub": "7375626A656374"
  },
  "events": {
    "https://schemas.openid.net/secevent/risc/event-type/account-disabled": {
      "reason": "hijacking"
    }
  }
}
```

--------------------------------

### Example: SET Containing an SSF Event with a Proprietary Subject Identifier Format

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

Shows how to use a custom, proprietary subject identifier format within a CAEP event.

```json
{
  "iss": "https://myservice.example3.com/",
  "jti": "756E69717565206964656E746966696534",
  "iat": 15203800012,
  "txn": "8675309",
  "aud": "636C69656E745F6324",
  "sub_id": {
    "format": "catalog_item",
    "catalog_id": "c0384/winter/2354122"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
      "event_timestamp": 1600975810,
      "claims": {
         "role": "ro-admin"
      }
    }
  }
}
```

--------------------------------

### HTTP Response for Stream Configuration

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

An example HTTP 200 OK response containing the JSON representation of an Event Stream's configuration. This includes details like stream ID, issuer, audience, delivery method, and supported/requested events.

```json
{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "iss": "https://tr.example.com",
  "aud": [
    "https://receiver.example.com/web",
    "https://receiver.example.com/mobile"
  ],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/events"
  },
  "events_supported": [
    "urn:example:secevent:events:type_1",
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "events_delivered": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "description": "Stream for Receiver A using events type_2, type_3, type_4"
}
```

--------------------------------

### Example: Security Event Token (SET) with array 'aud' claim

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

This JSON object demonstrates a standard Security Event Token (SET) structure, including the 'iss' issuer claim, an array-based 'aud' audience claim, the 'txn' transaction identifier, and an 'events' object containing a specific verification event.

```json
{
  "jti": "123456",
  "iss": "https://transmitter.example.com",
  "aud": ["receiver.example.com/web", "receiver.example.com/mobile"],
  "iat": 1493856000,
  "txn": "8675309",
  "sub_id": {
    "format": "opaque",
    "id": "72e6991badb44e08a69672960053b342"
  },
  "events": {
    "https://schemas.openid.net/secevent/ssf/event-type/verification": {
      "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
    }
  }
}
```

--------------------------------

### Reading a Stream's Configuration

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

An Event Receiver gets the current configuration of a stream by making an HTTP GET request to the Configuration Endpoint. The 'stream_id' query parameter can be used to identify a specific stream, or omitted to retrieve a list of all available stream configurations.

```APIDOC
## GET /ssf/stream

### Description
Retrieves the configuration of an Event Stream. If 'stream_id' is provided, it returns the configuration for that specific stream. If 'stream_id' is omitted, it returns a list of all available stream configurations.

### Method
GET

### Endpoint
/ssf/stream

### Query Parameters
- **stream_id** (string) - Optional - The identifier for the Event Stream whose configuration is to be retrieved.

### Request Example (with stream_id)
```http
GET /ssf/stream?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
```

### Request Example (without stream_id)
```http
GET /ssf/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
```

### Response
#### Success Response (200)
- **stream_id** (string) - The unique identifier for the stream.
- **iss** (string) - The issuer identifier.
- **aud** (array of strings) - The audience identifiers.
- **delivery** (object) - Details about the delivery method and endpoint.
  - **method** (string) - The delivery method.
  - **endpoint_url** (string) - The URL for event delivery.
- **events_supported** (array of strings) - A list of supported event types.
- **events_requested** (array of strings) - A list of event types requested.
- **events_delivered** (array of strings) - A list of event types delivered.
- **description** (string) - An optional description of the stream.

#### Response Example (single stream)
```json
{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "iss": "https://tr.example.com",
  "aud": [
    "https://receiver.example.com/web",
    "https://receiver.example.com/mobile"
  ],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/events"
  },
  "events_supported": [
    "urn:example:secevent:events:type_1",
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "events_delivered": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "description": "Stream for Receiver A using events type_2, type_3, type_4"
}
```

#### Response Example (multiple streams)
```json
[
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "description": "Stream for Receiver A using events type_2, type_3, type_4"
  },
  {
    "stream_id": "50b2d39934264897902c0581ba7c21a3",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "description": "Stream for Receiver A using events type_2, type_3, type_4"
  }
]
```

#### Response Example (empty list)
```json
[]
```
```

--------------------------------

### Example: SET Containing a RISC Event with a Phone Number Subject

Source: https://github.com/openid/sharedsignals/blob/main/openid-sharedsignals-framework-1_0.md

Shows a RISC event triggered by a phone number subject, including a specific reason for the account-disabled event.

```json
{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "phone_number",
    "phone_number": "+1 206 555 0123"
  },
  "events": {
    "https://schemas.openid.net/secevent/risc/event-type/account-disabled": {
      "reason": "hijacking"
    }
  }
}
```