Skip to content

Commit 0bed9f7

Browse files
NSeydouxedwardsph
NSeydoux
and
edwardsph
authored
Use the v2 Access Grant JSON-LD context (#1209)
* Use the v2 Access Grant JSON-LD context * Use provider config for context negotiation: The ESS VC provider exposes a .well-known including a context, it can be used to determine the latest context supported by the server and adapt the client accordingly. --------- Co-authored-by: Pete Edwards <edwardsph@users.noreply.github.com>
1 parent cd296c4 commit 0bed9f7

15 files changed

+408
-209
lines changed

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,14 @@ The following changes are pending, and will be applied on the next major release
1616

1717
## Unreleased
1818

19+
### New feature
20+
21+
- Passes the v2 of the JSON-LD context for Access Grants when issuing and using the
22+
`/derive` endpoint. This allows the server to return all Access Credentials understood
23+
by the client, both v1 and v2. Clients prior to this version will issue and retrieve
24+
Access Credentials with a v1 context (and will not be able to use features introduced
25+
in v2).
26+
1927
### Bugfix
2028

2129
- Type declarations have been altered so that internal type declarations are no longer

‎src/common/providerConfig.mock.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
//
2+
// Copyright Inrupt Inc.
3+
//
4+
// Permission is hereby granted, free of charge, to any person obtaining a copy
5+
// of this software and associated documentation files (the "Software"), to deal in
6+
// the Software without restriction, including without limitation the rights to use,
7+
// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
8+
// Software, and to permit persons to whom the Software is furnished to do so,
9+
// subject to the following conditions:
10+
//
11+
// The above copyright notice and this permission notice shall be included in
12+
// all copies or substantial portions of the Software.
13+
//
14+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
15+
// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
16+
// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
17+
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
18+
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
19+
// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20+
//
21+
22+
export const mockProviderConfig = ({ context }: { context?: string }) => ({
23+
"@context": [
24+
"https://www.w3.org/2018/credentials/v1",
25+
context ?? "https://schema.inrupt.com/credentials/v2.jsonld",
26+
],
27+
issuerService: "https://vc.inrupt.com/issue",
28+
statusService: "https://vc.inrupt.com/status",
29+
verifierService: "https://vc.inrupt.com/verify",
30+
derivationService: "https://vc.inrupt.com/derive",
31+
proofService: null,
32+
availabilityService: null,
33+
submissionService: null,
34+
queryService: "https://vc.inrupt.com/query",
35+
supportedSignatureTypes: ["https://w3id.org/security#Ed25519Signature2020"],
36+
});

‎src/common/providerConfig.test.ts‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
//
2+
// Copyright Inrupt Inc.
3+
//
4+
// Permission is hereby granted, free of charge, to any person obtaining a copy
5+
// of this software and associated documentation files (the "Software"), to deal in
6+
// the Software without restriction, including without limitation the rights to use,
7+
// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
8+
// Software, and to permit persons to whom the Software is furnished to do so,
9+
// subject to the following conditions:
10+
//
11+
// The above copyright notice and this permission notice shall be included in
12+
// all copies or substantial portions of the Software.
13+
//
14+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
15+
// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
16+
// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
17+
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
18+
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
19+
// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20+
//
21+
22+
import { jest, it, describe, expect, beforeEach } from "@jest/globals";
23+
import {
24+
buildProviderContext,
25+
DEFAULT_CONTEXT,
26+
getIssuerContext,
27+
clearProviderCache,
28+
} from "./providerConfig";
29+
import { mockProviderConfig } from "./providerConfig.mock";
30+
31+
describe("getIssuerContext", () => {
32+
beforeEach(() => {
33+
clearProviderCache();
34+
});
35+
36+
it("fetches the issuer config to read its context", async () => {
37+
const mockedConfig = mockProviderConfig({});
38+
jest
39+
.spyOn(globalThis, "fetch")
40+
.mockResolvedValueOnce(new Response(JSON.stringify(mockedConfig)));
41+
const ctx = await getIssuerContext(new URL("https://vc.example.org"));
42+
expect(ctx).toBe(mockedConfig["@context"][1]);
43+
});
44+
45+
it("caches the issuer config on subsequent calls", async () => {
46+
const mockedConfig = mockProviderConfig({});
47+
const mockedFetch = jest
48+
.spyOn(globalThis, "fetch")
49+
.mockResolvedValueOnce(new Response(JSON.stringify(mockedConfig)));
50+
const ctx1 = await getIssuerContext(new URL("https://vc.example.org"));
51+
const ctx2 = await getIssuerContext(new URL("https://vc.example.org"));
52+
const ctx3 = await getIssuerContext(new URL("https://vc.example.org"));
53+
expect(mockedFetch).toHaveBeenCalledTimes(1);
54+
expect(ctx1).toBe(mockedConfig["@context"][1]);
55+
expect(ctx2).toBe(mockedConfig["@context"][1]);
56+
expect(ctx3).toBe(mockedConfig["@context"][1]);
57+
});
58+
});
59+
60+
describe("buildIssuerContext", () => {
61+
it("uses the context from the provider if supported", async () => {
62+
const mockedConfig1 = mockProviderConfig({
63+
context: "https://schema.inrupt.com/credentials/v1.jsonld",
64+
});
65+
const mockedConfig2 = mockProviderConfig({
66+
context: "https://schema.inrupt.com/credentials/v2.jsonld",
67+
});
68+
jest
69+
.spyOn(globalThis, "fetch")
70+
.mockResolvedValueOnce(new Response(JSON.stringify(mockedConfig1)))
71+
.mockResolvedValueOnce(new Response(JSON.stringify(mockedConfig2)));
72+
const v1Ctxs = await buildProviderContext(
73+
new URL("https://vc.v1.example.org"),
74+
);
75+
expect(v1Ctxs).toContain(mockedConfig1["@context"][1]);
76+
const v2Ctxs = await buildProviderContext(
77+
new URL("https://vc.v2.example.org"),
78+
);
79+
expect(v2Ctxs).toContain(mockedConfig2["@context"][1]);
80+
});
81+
82+
it("uses the latest supported context if the provider uses an unknown context", async () => {
83+
const mockedConfig = mockProviderConfig({
84+
context: "https://schema.inrupt.com/credentials/v999.jsonld",
85+
});
86+
87+
jest
88+
.spyOn(globalThis, "fetch")
89+
.mockResolvedValueOnce(new Response(JSON.stringify(mockedConfig)));
90+
const ctxs = await buildProviderContext(new URL("https://vc.example.org"));
91+
expect(ctxs).not.toContain(mockedConfig["@context"][1]);
92+
expect(ctxs).toContain(DEFAULT_CONTEXT);
93+
});
94+
});

‎src/common/providerConfig.ts‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
//
2+
// Copyright Inrupt Inc.
3+
//
4+
// Permission is hereby granted, free of charge, to any person obtaining a copy
5+
// of this software and associated documentation files (the "Software"), to deal in
6+
// the Software without restriction, including without limitation the rights to use,
7+
// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
8+
// Software, and to permit persons to whom the Software is furnished to do so,
9+
// subject to the following conditions:
10+
//
11+
// The above copyright notice and this permission notice shall be included in
12+
// all copies or substantial portions of the Software.
13+
//
14+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
15+
// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
16+
// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
17+
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
18+
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
19+
// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20+
//
21+
22+
import { CONTEXT_VC_W3C } from "../gConsent/constants";
23+
24+
export const SUPPORTED_CONTEXTS = [
25+
"https://schema.inrupt.com/credentials/v1.jsonld",
26+
"https://schema.inrupt.com/credentials/v2.jsonld",
27+
] as const;
28+
29+
const SELF_HOSTED_URI_TEMPLATE = "https://{DOMAIN}/credentials/v1";
30+
const instantiateSelfHosted = (domain: string) =>
31+
SELF_HOSTED_URI_TEMPLATE.replace("{DOMAIN}", domain);
32+
33+
// The type assertion is required because TS doesn't validate the const array size vs the index.
34+
export const DEFAULT_CONTEXT = SUPPORTED_CONTEXTS.at(
35+
-1,
36+
) as (typeof SUPPORTED_CONTEXTS)[number];
37+
const WELL_KNOWN_CONFIG = "/.well-known/vc-configuration";
38+
39+
export type AccessProvider = {
40+
context: (typeof SUPPORTED_CONTEXTS)[number] | string;
41+
};
42+
43+
const providerCache: Record<string, AccessProvider> = {};
44+
45+
/**
46+
* This is an internal function to avoid having to mock fetch on all tests.
47+
* @hidden
48+
*/
49+
export function cacheProvider(url: string, provider: AccessProvider) {
50+
providerCache[url] = provider;
51+
}
52+
53+
/**
54+
* This is an internal function to avoid having to mock fetch on all tests.
55+
* @hidden
56+
*/
57+
export function clearProviderCache() {
58+
Object.keys(providerCache).forEach((url) => {
59+
delete providerCache[url];
60+
});
61+
}
62+
63+
/**
64+
* This internal function negotiates the most recent context supported by both the provider and the client.
65+
* It also caches the result in memory so that the VC provider configuration is only fetched once.
66+
* FIXME: use proper caching for eventual eviction.
67+
*/
68+
export async function getIssuerContext(
69+
issuer: URL,
70+
): Promise<(typeof SUPPORTED_CONTEXTS)[number] | undefined | string> {
71+
if (providerCache[issuer.href] !== undefined) {
72+
return providerCache[issuer.href].context;
73+
}
74+
const configUrl = new URL(WELL_KNOWN_CONFIG, issuer);
75+
const response = await fetch(configUrl);
76+
try {
77+
const config = await response.json();
78+
const contexts = config["@context"] as Array<string>;
79+
let providerCtx = contexts.find((ctx) =>
80+
// Typescript is too strict validating consts.
81+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
82+
SUPPORTED_CONTEXTS.includes(ctx as any),
83+
);
84+
const selfHosted = instantiateSelfHosted(issuer.hostname);
85+
// If no canonical context is being used, check for self-hosted (applicable to ESS 2.2).
86+
if (providerCtx === undefined && contexts.indexOf(selfHosted) !== -1) {
87+
// If the well-known config uses a self-hosted context, canonical v1 should be used.
88+
[providerCtx] = SUPPORTED_CONTEXTS;
89+
}
90+
if (providerCtx !== undefined) {
91+
providerCache[issuer.href] = { context: providerCtx };
92+
}
93+
return providerCtx;
94+
} catch (e) {
95+
// We don't want this issue to be swallowed silently.
96+
// eslint-disable-next-line no-console
97+
console.error(e);
98+
}
99+
return undefined;
100+
}
101+
102+
export const buildProviderContext = async (
103+
issuer: URL,
104+
): Promise<Array<string>> => [
105+
CONTEXT_VC_W3C,
106+
// If the issuer uses a context we don't support, default to the latest supported.
107+
(await getIssuerContext(issuer)) ?? DEFAULT_CONTEXT,
108+
];

‎src/fetch/index.test.ts‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -168,10 +168,7 @@ describe("exchangeTicketForAccessToken", () => {
168168
body: new URLSearchParams({
169169
claim_token: isomorphicBtoa(
170170
JSON.stringify({
171-
"@context": [
172-
"https://www.w3.org/2018/credentials/v1",
173-
"https://schema.inrupt.com/credentials/v1.jsonld",
174-
],
171+
"@context": ["https://www.w3.org/2018/credentials/v1"],
175172
type: ["VerifiablePresentation"],
176173
verifiableCredential: [MOCK_VC],
177174
}),

‎src/fetch/index.ts‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,7 @@ import type {
2525
} from "@inrupt/solid-client-vc";
2626
import type { UmaConfiguration } from "../type/UmaConfiguration";
2727
import type { FetchOptions } from "../type/FetchOptions";
28-
import {
29-
CONTEXT_VC_W3C,
30-
CONTEXT_ESS_DEFAULT,
31-
PRESENTATION_TYPE_BASE,
32-
} from "../gConsent/constants";
28+
import { CONTEXT_VC_W3C, PRESENTATION_TYPE_BASE } from "../gConsent/constants";
3329
import { UmaError } from "../common/errors/UmaError";
3430

3531
const WWW_AUTH_HEADER = "www-authenticate";
@@ -102,7 +98,8 @@ export async function exchangeTicketForAccessToken(
10298
authFetch: typeof fetch,
10399
): Promise<string | null> {
104100
const credentialPresentation = {
105-
"@context": [CONTEXT_VC_W3C, CONTEXT_ESS_DEFAULT],
101+
// This is the presentation context, so only the W3C context is required.
102+
"@context": [CONTEXT_VC_W3C],
106103
type: [PRESENTATION_TYPE_BASE],
107104
verifiableCredential: [accessGrant],
108105
};

‎src/gConsent/constants.ts‎

Lines changed: 3 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
//
2121

2222
import { gc } from "../common/constants";
23+
import { DEFAULT_CONTEXT } from "../common/providerConfig";
2324

2425
export const GC_CONSENT_STATUS_DENIED_ABBREV = "ConsentStatusDenied";
2526
export const GC_CONSENT_STATUS_EXPLICITLY_GIVEN_ABBREV =
@@ -36,15 +37,6 @@ export const PREFERRED_CONSENT_MANAGEMENT_UI =
3637
"http://inrupt.com/ns/ess#ConsentManagementUI";
3738

3839
export const CONTEXT_VC_W3C = "https://www.w3.org/2018/credentials/v1" as const;
39-
// This static context is used from the 2.1 version, instead of having a context
40-
// specific to the deployment.
41-
export const CONTEXT_ESS_DEFAULT =
42-
"https://schema.inrupt.com/credentials/v1.jsonld" as const;
43-
44-
// According to the [ESS documentation](https://docs.inrupt.com/ess/latest/services/service-vc/#ess-vc-service-endpoints),
45-
// the JSON-LD context for ESS-issued VCs will match the following template.
46-
const instanciateContextVcEssTemplate = (essVcDomain: string): string =>
47-
`https://${essVcDomain}/credentials/v1`;
4840

4941
const extraContext = [
5042
"https://w3id.org/security/data-integrity/v1",
@@ -53,28 +45,12 @@ const extraContext = [
5345
"https://w3id.org/security/suites/ed25519-2020/v1",
5446
];
5547

56-
// A default context value is provided for mocking purpose accross the codebase.
57-
export const ACCESS_GRANT_CONTEXT_DEFAULT = [
58-
CONTEXT_VC_W3C,
59-
CONTEXT_ESS_DEFAULT,
60-
instanciateContextVcEssTemplate("vc.inrupt.com"),
61-
] as const;
62-
6348
export const MOCK_CONTEXT = [
64-
...ACCESS_GRANT_CONTEXT_DEFAULT,
49+
CONTEXT_VC_W3C,
50+
DEFAULT_CONTEXT,
6551
...extraContext,
6652
] as const;
6753

68-
// When issuing a VC using a given service,"https://schema.inrupt.com/credentials/v1.jsonld" be sure to set the context using the following.
69-
export const instanciateEssAccessGrantContext = (
70-
essVcDomain: string,
71-
): typeof ACCESS_GRANT_CONTEXT_DEFAULT =>
72-
[
73-
CONTEXT_VC_W3C,
74-
CONTEXT_ESS_DEFAULT,
75-
instanciateContextVcEssTemplate(essVcDomain),
76-
] as const;
77-
7854
export const CREDENTIAL_TYPE_ACCESS_REQUEST = "SolidAccessRequest";
7955
export const CREDENTIAL_TYPE_ACCESS_GRANT = "SolidAccessGrant";
8056
export const CREDENTIAL_TYPE_ACCESS_DENIAL = "SolidAccessDenial";

‎src/gConsent/manage/approveAccessRequest.test.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ import {
3838
mockConsentGrantVc,
3939
mockConsentRequestVc,
4040
} from "../util/access.mock";
41+
import { cacheProvider, DEFAULT_CONTEXT } from "../../common/providerConfig";
4142

4243
jest.mock("@inrupt/solid-client", () => {
4344
const solidClientModule = jest.requireActual(
@@ -145,6 +146,9 @@ describe("approveAccessRequest", () => {
145146
accessGrantVc = await mockAccessGrantVc();
146147
consentRequestVc = await mockConsentRequestVc();
147148
consentGrantVc = await mockConsentGrantVc();
149+
cacheProvider(new URL(MOCKED_ACCESS_ISSUER).href, {
150+
context: DEFAULT_CONTEXT,
151+
});
148152
});
149153

150154
// FIXME: This test must run before the other tests mocking the ACP client.
@@ -349,6 +353,9 @@ describe("approveAccessRequest", () => {
349353

350354
it("uses the provided access endpoint, if any", async () => {
351355
mockAcpClient();
356+
cacheProvider(new URL("https://some.consent-endpoint.override/").href, {
357+
context: DEFAULT_CONTEXT,
358+
});
352359
const mockedVcModule = jest.requireMock(
353360
"@inrupt/solid-client-vc",
354361
) as typeof VcClient;

‎src/gConsent/manage/denyAccessRequest.test.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ import type { AccessGrant } from "../type/AccessGrant";
4444
import { mockAccessGrantVc, mockAccessRequestVc } from "../util/access.mock";
4545
import { normalizeAccessGrant } from "./approveAccessRequest";
4646
import { denyAccessRequest } from "./denyAccessRequest";
47+
import { cacheProvider, DEFAULT_CONTEXT } from "../../common/providerConfig";
4748

4849
jest.mock("@inrupt/solid-client", () => {
4950
const solidClientModule = jest.requireActual("@inrupt/solid-client") as any;
@@ -70,6 +71,12 @@ describe("denyAccessRequest", () => {
7071

7172
beforeAll(async () => {
7273
accessRequestVc = await mockAccessRequestVc();
74+
cacheProvider(new URL(MOCKED_ACCESS_ISSUER).href, {
75+
context: DEFAULT_CONTEXT,
76+
});
77+
cacheProvider(new URL("https://some.access-endpoint.override/").href, {
78+
context: DEFAULT_CONTEXT,
79+
});
7380
});
7481

7582
afterEach(() => {

0 commit comments

Comments
 (0)