@verii/credentialing-hub-operator-api 0.0.0-stage → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,22 @@
1
+ /*
2
+ * Copyright 2026 Velocity Team
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ *
16
+ */
17
+
18
+ // The id of a Hub entity, such as a service or a depot: a MongoDB ObjectId
19
+ // as 24 hex digits, in either case.
20
+ const OBJECT_ID_PATTERN = '^[0-9a-fA-F]{24}$';
21
+
22
+ module.exports = { OBJECT_ID_PATTERN };
@@ -0,0 +1,134 @@
1
+ /*
2
+ * Copyright 2026 Velocity Team
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ *
16
+ */
17
+ const Ajv = require('ajv');
18
+ const addFormats = require('ajv-formats');
19
+ const { forEach, isEmpty } = require('lodash/fp');
20
+ const {
21
+ newOfferRelatedResourceSchema,
22
+ w3cVcSchema,
23
+ } = require('@verii/common-schemas');
24
+ const { initValidation, wrapValidationError } = require('@verii/validation');
25
+ const {
26
+ findDepotsRequestSchema,
27
+ newCredentialSchema,
28
+ newDepotSchema,
29
+ newIssuerServiceSchema,
30
+ } = require('./schemas');
31
+
32
+ // The defaults of @fastify/ajv-compiler, which builds the Hub's validators.
33
+ // The Hub's options below override all but addUsedSchema.
34
+ const FASTIFY_AJV_DEFAULTS = {
35
+ coerceTypes: 'array',
36
+ useDefaults: true,
37
+ removeAdditional: true,
38
+ addUsedSchema: false,
39
+ allErrors: false,
40
+ };
41
+
42
+ // The Hub's `ajvOptions`. A Hub test checks they stay the same.
43
+ const operatorApiAjvOptions = Object.freeze({
44
+ removeAdditional: false,
45
+ useDefaults: false,
46
+ coerceTypes: false,
47
+ allErrors: false,
48
+ strictTypes: 'log',
49
+ });
50
+
51
+ // The Hub's `ajvFormats`, which it takes from @verii/config. A Hub test checks
52
+ // they stay the same.
53
+ const operatorApiAjvFormats = Object.freeze([
54
+ 'uri',
55
+ 'uri-reference',
56
+ 'iri',
57
+ 'iri-reference',
58
+ 'date',
59
+ 'date-time',
60
+ 'regex',
61
+ 'email',
62
+ 'duration',
63
+ ]);
64
+
65
+ // Schemas that the request schemas $ref
66
+ const REFERENCED_SCHEMAS = [newOfferRelatedResourceSchema, w3cVcSchema];
67
+
68
+ const REQUEST_SCHEMAS = [
69
+ newIssuerServiceSchema,
70
+ newDepotSchema,
71
+ newCredentialSchema,
72
+ findDepotsRequestSchema,
73
+ ];
74
+
75
+ /**
76
+ * Builds a validator for the Hub's operator API request schemas
77
+ * (`new-issuer-service`, `new-depot`, `new-credential` and
78
+ * `find-depots-request`), with the AJV
79
+ * options and formats the Hub uses, so a client accepts what the Hub accepts.
80
+ * It never changes the data: defaults aren't applied and types aren't coerced.
81
+ * @returns {{
82
+ * validate: (schemaId: string, data: unknown) => Array<object>,
83
+ * assertValid: (schemaId: string, data: unknown, dataVar?: string) => unknown,
84
+ * }} the validator
85
+ */
86
+ const initOperatorApiValidator = () => {
87
+ const ajv = new Ajv({ ...FASTIFY_AJV_DEFAULTS, ...operatorApiAjvOptions });
88
+ addFormats(ajv, operatorApiAjvFormats);
89
+ const { addDocSchema, getDocValidator } = initValidation(ajv);
90
+ forEach(addDocSchema, [...REFERENCED_SCHEMAS, ...REQUEST_SCHEMAS]);
91
+
92
+ const getValidator = (schemaId) => {
93
+ const validateFn = getDocValidator(schemaId);
94
+ if (validateFn == null) {
95
+ throw new Error(`Unknown operator API schema "${schemaId}"`);
96
+ }
97
+ return validateFn;
98
+ };
99
+
100
+ /**
101
+ * Validates data against a schema.
102
+ * @param {string} schemaId the schema's `$id`, for example `new-depot`
103
+ * @param {unknown} data the data to validate
104
+ * @returns {Array<object>} the AJV errors, or an empty array when the data is valid
105
+ */
106
+ const validate = (schemaId, data) => {
107
+ const validateFn = getValidator(schemaId);
108
+ return validateFn(data) ? [] : validateFn.errors;
109
+ };
110
+
111
+ /**
112
+ * Validates data against a schema, and throws when it is invalid.
113
+ * @param {string} schemaId the schema's `$id`, for example `new-depot`
114
+ * @param {unknown} data the data to validate
115
+ * @param {string} [dataVar] the prefix of the error message. Defaults to the schema's `$id`
116
+ * @returns {unknown} the data, when it is valid
117
+ * @throws {Error} a 400 error with the message format and `validation` errors that Fastify gives
118
+ */
119
+ const assertValid = (schemaId, data, dataVar = schemaId) => {
120
+ const errors = validate(schemaId, data);
121
+ if (!isEmpty(errors)) {
122
+ throw wrapValidationError(errors, dataVar);
123
+ }
124
+ return data;
125
+ };
126
+
127
+ return { validate, assertValid };
128
+ };
129
+
130
+ module.exports = {
131
+ initOperatorApiValidator,
132
+ operatorApiAjvFormats,
133
+ operatorApiAjvOptions,
134
+ };
@@ -0,0 +1,121 @@
1
+ /*
2
+ * Copyright 2026 Velocity Team
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ *
16
+ */
17
+ const {
18
+ cond,
19
+ constant,
20
+ defaultTo,
21
+ filter,
22
+ find,
23
+ flatMap,
24
+ flatten,
25
+ flow,
26
+ get,
27
+ has,
28
+ isArray,
29
+ isEmpty,
30
+ isInteger,
31
+ isNull,
32
+ isPlainObject,
33
+ isString,
34
+ map,
35
+ size,
36
+ stubTrue,
37
+ uniq,
38
+ } = require('lodash/fp');
39
+ const { toAuthMatchValue } = require('./auth-match-values');
40
+ const { isOfValueType } = require('./auth-value-types');
41
+
42
+ const isArrayIndex = (component) => isInteger(component) && component >= 0;
43
+
44
+ // Each claims path pointer segment is a selector: it takes the selected
45
+ // elements and returns what it selects from them. A segment applies only to
46
+ // the elements it fits and drops the others, so a key never reads an array's or
47
+ // a string's length, and an index never reads a character of a string.
48
+
49
+ // A key selects that own property, never an inherited one, of each object. The
50
+ // path is an array, so a key such as "a.b" or "a[0]" is read as it is, not
51
+ // parsed as a path.
52
+ const selectKey = (key) =>
53
+ flow(filter(isPlainObject), filter(has([key])), map(get([key])));
54
+
55
+ // An index selects that element of each array.
56
+ const selectIndex = (index) =>
57
+ flow(filter(isArray), filter(has([index])), map(get([index])));
58
+
59
+ // null selects every element of each array.
60
+ const selectEvery = flow(filter(isArray), flatten);
61
+
62
+ const selectNothing = constant([]);
63
+
64
+ const segmentSelector = cond([
65
+ [isString, selectKey],
66
+ [isNull, constant(selectEvery)],
67
+ [isArrayIndex, selectIndex],
68
+ [stubTrue, constant(selectNothing)],
69
+ ]);
70
+
71
+ // Evaluates a claims path pointer (OpenID4VP 1.0, section 7) against a
72
+ // credential and returns what it selects. A string selects a key of each
73
+ // selected object, a non-negative integer an index of each selected array, and
74
+ // null every element of each selected array. Any other segment selects nothing.
75
+ // It never throws.
76
+ //
77
+ // An empty pointer selects nothing, rather than the credential. Otherwise each
78
+ // segment is a step that works on the list of values selected so far, starting
79
+ // from the credential.
80
+ const selectClaims = (pointer, credential) => {
81
+ if (!isArray(pointer) || isEmpty(pointer)) {
82
+ return [];
83
+ }
84
+ const steps = map(segmentSelector, pointer);
85
+ return flow(steps)([credential]);
86
+ };
87
+
88
+ // A rule's pointers are tried in order, and the first one that selects a
89
+ // usable value supplies the values. A selection of only nulls, objects, arrays
90
+ // or values of another type than the rule's falls through to the next pointer.
91
+ // A rule has at most 10 pointers, so every pointer is evaluated. A path that
92
+ // isn't an array reads nothing: map would walk an object's values as if they
93
+ // were pointers.
94
+ const firstUsableValues = (pointers, isUsable, credential) => {
95
+ if (!isArray(pointers)) {
96
+ return [];
97
+ }
98
+ const selectFromCredential = (pointer) => selectClaims(pointer, credential);
99
+ const usableValues = flow(selectFromCredential, filter(isUsable));
100
+ return flow(map(usableValues), find(size), defaultTo([]))(pointers);
101
+ };
102
+
103
+ // The distinct normalized values of the rule's valueType that a rule finds in
104
+ // the credentials of its type. Values of another type are ignored, never
105
+ // converted. credentials are { type, credential } for each verified
106
+ // credential.
107
+ const ruleValues = (rule, credentials) => {
108
+ const isOfRuleType = ({ type }) => type === rule.type;
109
+ const isUsable = isOfValueType(rule.valueType);
110
+ const valuesInCredential = (credential) =>
111
+ firstUsableValues(rule.path, isUsable, credential);
112
+ return flow(
113
+ filter(isOfRuleType),
114
+ map('credential'),
115
+ flatMap(valuesInCredential),
116
+ map(toAuthMatchValue),
117
+ uniq,
118
+ )(credentials);
119
+ };
120
+
121
+ module.exports = { ruleValues, selectClaims };