@finsys/core 4.2.0 → 4.3.0

package/dist/index.d.cts

@@ -1470,6 +1470,30 @@ interface AdapterManifest {
      * present — declaring them is harmless but unnecessary.
      */
     readonly requiredIdentityFields?: ReadonlyArray<string>;
+    /**
+     * SYS-2503: declarative per-field authorization gating. Keyed by
+     * canonical field name (every key MUST also appear in `produces` —
+     * host validates at registration, same as `singletonFields`).
+     *
+     * Semantics, enforced by the HOST at read time (the manifest only
+     * declares):
+     *
+     *   - No entry for a field → visible to every reader (gating is
+     *     strictly opt-in; pre-existing manifests are unaffected).
+     *   - An entry restricts: the reader must satisfy EVERY dimension
+     *     the entry declares (AND across dimensions), matching ANY value
+     *     within a dimension's list (OR within a list).
+     *   - `lenderRoles` — reader's lender-role identifier must be listed.
+     *   - `programIds` — the application's program must be listed.
+     *
+     * Both dimensions are host-interpreted opaque strings: core neither
+     * knows nor validates what a "role" or "program id" is, keeping the
+     * contract deployment-agnostic. An entry must declare at least one
+     * dimension, and a declared dimension must be non-empty — an empty
+     * list would read as deny-all, which is better expressed by simply
+     * not producing the field.
+     */
+    readonly fieldAuthorizations?: Readonly<Partial<Record<CanonicalFieldName, FieldAuthorization>>>;
     /**
      * Optional free-form notes — useful for partner-side documentation
      * (where to find the adapter's source, who owns it, what version of
@@ -1477,6 +1501,22 @@ interface AdapterManifest {
      */
     readonly notes?: string;
 }
+/**
+ * SYS-2503: one field's authorization gate. See
+ * {@link AdapterManifest.fieldAuthorizations} for semantics.
+ *
+ * A union rather than an all-optional interface so a no-op gate (`{}`)
+ * is unrepresentable at COMPILE time too, not just rejected by the JSON
+ * schema's `minProperties: 1` at runtime — the TS type and the schema
+ * enforce the same invariant at their respective layers.
+ */
+type FieldAuthorization = {
+    readonly lenderRoles: ReadonlyArray<string>;
+    readonly programIds?: ReadonlyArray<string>;
+} | {
+    readonly lenderRoles?: ReadonlyArray<string>;
+    readonly programIds: ReadonlyArray<string>;
+};
 interface DeclarativeImplementation {
     readonly type: "declarative";
     /**
@@ -1561,4 +1601,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.d.ts

@@ -1470,6 +1470,30 @@ interface AdapterManifest {
      * present — declaring them is harmless but unnecessary.
      */
     readonly requiredIdentityFields?: ReadonlyArray<string>;
+    /**
+     * SYS-2503: declarative per-field authorization gating. Keyed by
+     * canonical field name (every key MUST also appear in `produces` —
+     * host validates at registration, same as `singletonFields`).
+     *
+     * Semantics, enforced by the HOST at read time (the manifest only
+     * declares):
+     *
+     *   - No entry for a field → visible to every reader (gating is
+     *     strictly opt-in; pre-existing manifests are unaffected).
+     *   - An entry restricts: the reader must satisfy EVERY dimension
+     *     the entry declares (AND across dimensions), matching ANY value
+     *     within a dimension's list (OR within a list).
+     *   - `lenderRoles` — reader's lender-role identifier must be listed.
+     *   - `programIds` — the application's program must be listed.
+     *
+     * Both dimensions are host-interpreted opaque strings: core neither
+     * knows nor validates what a "role" or "program id" is, keeping the
+     * contract deployment-agnostic. An entry must declare at least one
+     * dimension, and a declared dimension must be non-empty — an empty
+     * list would read as deny-all, which is better expressed by simply
+     * not producing the field.
+     */
+    readonly fieldAuthorizations?: Readonly<Partial<Record<CanonicalFieldName, FieldAuthorization>>>;
     /**
      * Optional free-form notes — useful for partner-side documentation
      * (where to find the adapter's source, who owns it, what version of
@@ -1477,6 +1501,22 @@ interface AdapterManifest {
      */
     readonly notes?: string;
 }
+/**
+ * SYS-2503: one field's authorization gate. See
+ * {@link AdapterManifest.fieldAuthorizations} for semantics.
+ *
+ * A union rather than an all-optional interface so a no-op gate (`{}`)
+ * is unrepresentable at COMPILE time too, not just rejected by the JSON
+ * schema's `minProperties: 1` at runtime — the TS type and the schema
+ * enforce the same invariant at their respective layers.
+ */
+type FieldAuthorization = {
+    readonly lenderRoles: ReadonlyArray<string>;
+    readonly programIds?: ReadonlyArray<string>;
+} | {
+    readonly lenderRoles?: ReadonlyArray<string>;
+    readonly programIds: ReadonlyArray<string>;
+};
 interface DeclarativeImplementation {
     readonly type: "declarative";
     /**
@@ -1561,4 +1601,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/schema/adapter-manifest.schema.json

@@ -153,6 +153,31 @@
       "uniqueItems": true,
       "description": "v2.7.0 — partner-specific identity field names required by fetch(). Host validates per-applicant before invoking fetch() and skips the adapter when missing. Omit (or empty) for adapters that don't implement fetch(). Must NOT include core fields ('ihsId', 'ic', 'fullName') — those are always populated, and declaring 'ic' as required would cause the host to skip every non-MY applicant since 'ic' can legitimately be empty."
     },
+    "fieldAuthorizations": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "minLength": 1 },
+      "additionalProperties": {
+        "type": "object",
+        "minProperties": 1,
+        "additionalProperties": false,
+        "properties": {
+          "lenderRoles": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "programIds": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      },
+      "description": "SYS-2503 — declarative per-field authorization gating, keyed by canonical field name (every key must also appear in `produces`; host validates at registration). No entry → field visible to every reader. An entry restricts: reader must satisfy EVERY declared dimension (AND across dimensions), matching ANY value within a list (OR within). Dimensions are host-interpreted opaque strings. Each entry must declare at least one non-empty dimension — an empty list would read as deny-all, better expressed by not producing the field."
+    },
     "notes": {
       "type": "string",
       "maxLength": 2000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finsys/core",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Convert unified form configurations into Zod schemas, React Hook Form defaults, and SurveyJS JSON",
   "repository": {
     "type": "git",