Follow on from #20. This interoperability profile should include the ability to selectively disclose attributes of credentials. This is currently blocked because of a bug in the BBS+ LD signature suite. w3c/vc-di-bbs#62

We will continue to monitor the situation and include them here once possible.

The terminology section of the spec needs to be expanded on, as it is currently pretty barren.

consider:

POST /exchanges/credential-refresh
POST /exchanges/definition-oil-import-from-ca
POST /exchanges/definition-steel-import-from-mx

vs

POST /exchanges/urn:uuid:123

is guessable names a security issue?

if we support a single human readable name, does that mean we support all the other ones?

where is the registry for human readable "workflow definition names" maintained.

need to make sure HTML is clean and properly formatted before PRs go out etc

need some well defined correlation id or similar

The HTML output from postman tests should be available for review.

When errors occur, there should be helpful messages returned over http.

There should be an error message structure.

The structure should be used when handling 200 responses where the verification failed

There should also be a 400 error message structure, for cases where the client violates the api definition.

There should be test cases for errors, and each variant of an error.

There should be specific cases for revocation, expiration, preactivation.

https://github.com/w3c-ccg/traceability-interop/pull/50/files#r786921321

I suggest we mirror or directly link to the vc http api now that is has separate spec, and that we clearly separate endpoints not defined in the vc http api to avoid confusion.

CLIENT_SECRET_TRANSMUTE has been suggested

The postman test for revocation currently hard-codes the server name api.did.actor in the request URL for DID resolution. Instead, it should be using the API_BASE_URL environment variable.

Is it possible to use on CCG repos, so we can have PR previews.

See #15 (comment)

As they related to vc-api "workflows" with "names" and "id".

We will need be able to store some OAuth2 credentials for service providers to be able to retrieve a bearer token to run integration tests using the trace vocab against various VC-API providers complying with this interop profile.

These tests will run using newman from gh actions

@brownoxford can you take a task of documenting the right approach so that service providers could add credentials to be used with testing, might be as simple as gh secrets, but then we will need to figure out a storage process for a list of secrets that can be matched to a list of service providers to be tested, and document a process for securely sending that info over to an editor on this project so that the keys can be added

https://www.postman.com/postman/workspace/httpbin/request/15582611-23a19640-0289-494e-ba46-a38f997b7012

^ investigate, can we provide a UI on the collections in this repo?

@OR13 brought up this issue in another ticket, and we discussed possibly adding a key to the oauth2 section of the service provider JSON instead of dynamically coming up with a key using SHA256 and the client_id value.

{
    "didDocument": {
        "@context": [
            "https://www.w3.org/ns/did/v1",
            "https://w3id.org/security/suites/jws-2020/v1"
        ],
        "id": "did:key:z82LktXPpyJiLELpZ5gKT8eDSxWrbo9USNFeGzu12SZsemEhhGcQeehfVpEZBxP6fuEmQhq",
        ...

or

{
     "@context": [
         "https://www.w3.org/ns/did/v1",
         "https://w3id.org/security/suites/jws-2020/v1"
     ],
     "id": "did:key:z82LktXPpyJiLELpZ5gKT8eDSxWrbo9USNFeGzu12SZsemEhhGcQeehfVpEZBxP6fuEmQhq",
     ...

See: https://api.did.actor/docs#tag--Identifiers

WACI-PEx describes an alternate flow for exchanging verifiable presentations:

https://github.com/decentralized-identity/waci-presentation-exchange

Unlike the vc-http-api, it is built on top of message level encryption for DIDs, according to a spec called https://github.com/decentralized-identity/didcomm-messaging

The advantage of WACI-PEx is that messages can flow other transports other than HTTP.

The spec also makes use of https://github.com/decentralized-identity/presentation-exchange

Which defines extensions for verifiable presentations that a verifier can use to request specific kinds of presentations from holders.

I would like to define support for this once it stabilizes so we can establish interoperability with other DIF companies and TOIPs Good Health Pass.

I think for sanity sake, we would need new endpoints for this, luckily they would be generate "DIDComm" service endpoints.

We have this construct in several of the tests:
--reporters cli,jsonname: Mill Test Report Certificate Tests
which results in the following error:
newman: could not find "jsonname:" reporter

Everything after ,json should be removed.

The abstract talks about this being a vocab and the introduction talks about this being a platform. The abstract can probably be written at a later date and we can track that here

Need to add a list of required or suggested encryption methods for storing information at rest in systems conforming to the spec, e.g. AESxxx

Should we need to sign VPs when they are presented over a channel that is authenticated?

Can we improve performance by relying on the channel authentication?

How might this impact the VC-API and exchange APIs?

Current test in ci.yml uses the following conditional:

if: github.repository == github.event.repository.full_name

This does not seem to be working though.

We need to add workflow items to run the postman tests on push (secrets are not passed on PR from remote repos). This may require some additional work in getting the suite ready to run in this context. We should also look into how we can publish results of test runs for review (newman produces html artifacts).

Need a definition and core structure and description for the notion of workflows in the context of tracing an item or shipment

This proposal was made originally to link the VC Data Model and Universal Wallet and VC HTTP APIs, together in a way that would support interoperability across HTTP based wallets:

https://github.com/OR13/simple-presentations

We should discuss the associated assumed JSON models related to "handling presentations", including preserving of metadata etc...

Since this work is related to a number of active CCG work items, we may need to cross link here to provide sufficient context.

Need to add a section covering best practices for software supply chain vulnerability management in the "Security Considerations" section of the spec

We are using swagger-cli to generate docs/openapi/openapi.json based on the manually maintained docs/openapi/openapi.yml. When swagger-cli encounters a ref for the first time, it inlines that ref and then rewrites all subsequent references to point to the inline definition (see APIDevTools/swagger-cli#29).

This results in inlined definitions where we don't really want them, and very awkward references in other places - for example:

                      "title": "Verifiable Credential",
                      "type": "object",
                      "allOf": [
                        {
                          "$ref": "#/paths/~1api~1credentials~1issue/post/requestBody/content/application~1json/schema/properties/credential"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "proof": {
                              "$ref": "#/paths/~1credentials~1%7Bcredential-id%7D/get/responses/200/content/application~1json/schema/allOf/1/properties/proof"
                            }
                          }
                        }
                      ],

One solution here is to modify the openapi.yml file to add new components where needed and rearrange where things live in the file in order to coerce swagger-cli to do what we want - I'm not certain that that is guaranteed to work.

Another solution is to simply inline everything by using the --dereference argument. Since this file is generated, this seems like a better solution - more verbose for sure, but without the normal drift we might see from repeated code throughout the file.

The documentation at docs/discovery.md should include a section on the /identifiers DID resolution endpoint.

@brownoxford and @OR13, could you (temporarily) grant me admin privileges, so I can try adding the oauth secret.

https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository

We need to add a section in the spec on "Ethical, Privacy, Human Rights, and Related Considerations":

Probably replacement for the privacy considerations.

HTTP API integrations between trusted parties are a solved problem and do not require a new spec to provide support for the authorization we need.

• https://auth0.com/machine-to-machine
• https://developer.okta.com/docs/guides/implement-client-creds/overview/

These "Client Credentials" solutions are appropriate starting point for cross trust domain VC HTTP API operations.

This ticket seeks to gain consensus on their use with the vc http api.

For the sake of simplicity, lets assume 2 vendors wish to exchange presentations over https.

Vendor A -> Client Credentials App for Vendor B -> Vendor B uses app to access Vendor A's API.
Vendor B -> Client Credential App for Vendor A -> Vendor A uses app to access Vendor B's API.

OAuth client credentials setup is out of scope, but let us assume that each integration is identified with a CLIENT_ID and authenticated via a CLIENT_SECRET.

Before authenticated exchanges can be made, an application access_token's for each app must be obtained using the client credentials.

Vendor A's software integration uses the client credentials from Vendor B's client credentials app and vendor b's IDP to obtain an access token, see these docs for the standard way this is accomplished: auth0

curl --location --request POST 'https://vendor-b.auth0.com/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_id": "A's integration app for B's API",
"client_secret": "[You application client secret]",
"audience": "https://vendor-b.example.com",
"grant_type": "client_credentials"
}

once Vendor A' software has an access_token for Vendor B's API, the presentation exchange can begin, the flow is as follows:

Getting a Challenge for a flow

curl POST -H "Authorization: <ACCESS_TOKEN>" \
http://www.vendor-b.example.com/organizations/123/presentations/available  \
-d @./get-challengge-token-with-query-by-frame.json

{
  "query": [
    {
      "type": "RequestQueryByFrame",
      "credentialQuery": [
        {
          "type": [
            "VerifiableCredential",
            "CommercialInvoiceCertificate"
          ],
          "reason": "Wallet XYZ is ready to selectively disclose new credentials."
        }
      ]
    }
  ]
}

Response is expected to look like this:

{
  "query": [
    {
      "type": "QueryByFrame",
      "credentialQuery": {
        "frame": {
          "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://w3id.org/traceability/v1",
            "https://w3id.org/bbs/v1"
          ],
          "type": [
            "VerifiableCredential",
            "CommercialInvoiceCertificate"
          ],
          "credentialSubject": {
            "@explicit": true,
            "type": [
              "CommercialInvoice"
            ],
            "purchaseDate": {},
            "destinationCountry": {}
          }
        }
      }
    }
  ],
  "domain": "vendor-b.example.com",
  "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f"
}

Submitting a Presentation

curl POST -H "Authorization: <ACCESS_TOKEN>" \
http://www.vendor-b.example.com/organizations/123/presentations/submissions  \
-d @./submit-presentation.json

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "holder": "did:example:123",
  "type": "VerifiablePresentation",
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ]
    },
    {
      "id": "http://example.gov/credentials/3732"
    },
    {
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ]
    },
    {
      "issuer": "did:example:123"
    },
    {
      "issuanceDate": "2020-03-16T22:37:26.544Z"
    },
    {
      "credentialSubject": {
        "id": "did:example:123",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      }
    },
    {
      "proof": {
        "type": "Ed25519Signature2018",
        "created": "2020-04-02T18:28:08Z",
        "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
        "proofPurpose": "assertionMethod",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
      }
    }
  ],
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2020-04-02T18:28:08Z",
    "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
    "proofPurpose": "assertionMethod",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
  }
}

We need a document and process to collect use cases and requirements for this profile

they got removed from the vc api

https://github.com/w3c-ccg/traceability-interop/runs/5434018049?check_suite_focus=true

Seems like some changes in the recent release broke things, will need to review, and show them passing in CI.

Again.

We added support for https://github.com/w3c-ccg/ldp-bbs2020

to the vc-http-api here: https://vc.transmute.world/api/docs

We should come up with some exemplar credentials that would be good to provide examples of using this proof suite.

An almost complete working PoC here: http://didme.me/

See https://learning.postman.com/docs/sending-requests/visualizer/

We need to setup SOME visualization of postman reports asap, and iterate on it later.

At a minimum there should be a way to see the results of a report by visiting a web page, and there should be an index of the reports that helps you get to the latest run.

I think its fine for us to drop older reports over time, since a report from 2 years ago, means nothing today.

should getting my "wallet contents" be in scope for internal holder apis.

Do we need to define these endpoints here or in the vc-http-api?

I have been considering scenario where each vendor might certify other vendors that have demonstrated a capability to pass an interoperability test.

In an ideal world, this might even be wired to github actions so that certification was automatically revoked when the vendor stopped passing the tests.

I believe this can be accomplished via postman and github actions.

Please see https://w3c-ccg.github.io/create_work_item.html for details.

Creating a ticket as a placeholder to ensure that we sanitize newman reports before publishing them to github pages.

@mprorock Our team wants to add client credentials for a CCG test report application to this repo, and generate a conformance report using postman.

Can we set this up in CI with no authorization first, and then figure out how to pull client id and client secret from github secrets in CI second?

• Wire CI tests for postman without authorization
• Add CLIENT_ID and CLIENT_SECRET to GitHub Secrets
• Update Postman tests to use authorization

need a best practices section covering disaster recovery and ransomware mitigation in the "Security Considerations" section

Disabled a number of CI rules in PR #42 for the tests packages, as discussed on the PR @brownoxford volunteered to fix those.

RESOLVED: One of the authorization protocols that will be defined for use in the VC-HTTP-API MUST be OAuth 2 Client Credentials.

^ from the call, we should note this is a normative requirement.

What is the policy for feature and fix branches which have been merged, can those be deleted to clear out clutter? To be clear, I am volunteering to do this cleanup :)

IMO we should not be defining ANY terminology that is not relevant to the HTTP interop profile in this repo...

We should especially not be defining VP or VC data model items in this repo.

Also the current terminology is incorrectly defined.

Need to add guidelines for which encryption methods are suggested for use of communications over the network, e.g. TLS 1.3, along with suggested cipher suites

I propose we consolidate the api definitions, follow the OAS 3.0 boilerplate guidelines (split parameters, schemas, responses, resources).

and have the respec just link to the OAS 3 Redoc like we do in trace-vocab.

Happy to do the work if folks are ready for it to be done... here is a preview of what it should look like (minus branding):

https://api.did.actor/docs

(happy to apply W3C CCG branding if we have an asset for that).

@brownoxford, any chance I can ask you to kindly take a look at how the two serviceProviders we merged yesterday are running in the CI - I'm not sure where to see the result of it?

Locally running node . -n "Transmute DID Actor API" -d key works, but the report seems a bit off.

Running node . -n "Transmute" -d key I get the error below. Any thoughts on what might be causing it? Any pointers on how I can progress would be hugely appreciated!

Traceability Interop Testing
Liveness check starting...
Quick liveness tests on service providers...
Skipping mesur.io due to config
Checking Transmute
file:///Users/nis/git/traceability-interop/packages/tests-postman/node_modules/ky/distribution/utils/time.js:8
        reject(new TimeoutError(request));
               ^

TimeoutError: Request timed out
    at Timeout.<anonymous> (file:///Users/nis/git/traceability-interop/packages/tests-postman/node_modules/ky/distribution/utils/time.js:8:16)
    at listOnTimeout (node:internal/timers:557:17)
    at processTimers (node:internal/timers:500:7) {
  request: Request {
    size: 0,
    follow: 20,
    compress: true,
    counter: 0,
    agent: undefined,
    highWaterMark: 16384,
    insecureHTTPParser: false,
    [Symbol(Body internals)]: { body: null, boundary: null, disturbed: false, error: null },
    [Symbol(Request internals)]: {
      method: 'HEAD',
      redirect: 'follow',
      headers: Headers { [Symbol(query)]: [], [Symbol(context)]: null },
      parsedURL: <ref *1> URL {
        [Symbol(context)]: URLContext {
          flags: 400,
          scheme: 'https:',
          username: '',
          password: '',
          host: 'platform.transmute.industries',
          port: null,
          path: [ '.well-known', 'did-configuration.json' ],
          query: null,
          fragment: null
        },
        [Symbol(query)]: URLSearchParams {
          [Symbol(query)]: [],
          [Symbol(context)]: [Circular *1]
        }
      },
      signal: AbortSignal {
        [Symbol(kEvents)]: SafeMap(0) [Map] {},
        [Symbol(events.maxEventTargetListeners)]: 10,
        [Symbol(events.maxEventTargetListenersWarned)]: false,
        [Symbol(kAborted)]: true
      }
    }
  }
}