gdc-common-utils-ts 2.5.11 → 2.5.12

package/dist/examples/index.d.ts

@@ -9,6 +9,7 @@ export * from './individual-controller';
 export * from './professional';
 export * from './employee';
 export * from './license';
+export * from './organization-role-license';
 export * from './invoice';
 export * from './inter-tenant-access-contract';
 export * from './subject-identity-binding';

package/dist/examples/index.js

@@ -9,6 +9,7 @@ export * from './individual-controller.js';
 export * from './professional.js';
 export * from './employee.js';
 export * from './license.js';
+export * from './organization-role-license.js';
 export * from './invoice.js';
 export * from './inter-tenant-access-contract.js';
 export * from './subject-identity-binding.js';

package/dist/examples/organization-role-license.d.ts

@@ -0,0 +1,16 @@
+import type { OrganizationRoleLicense } from '../models/organization-role-license';
+import { type OrganizationRoleLicenseIdentity } from '../utils/organization-role-license';
+/** Reusable synthetic identity for role-licence contract and consumer tests. */
+export declare const EXAMPLE_ORGANIZATION_ROLE_LICENSE_IDENTITY: OrganizationRoleLicenseIdentity;
+/** Reusable catch-all plus exact-override policy example. */
+export declare const EXAMPLE_ORGANIZATION_ROLE_LICENSE_POLICIES: readonly (Readonly<{
+    sector: "";
+    active: true;
+    maxDevices: null;
+}> | Readonly<{
+    sector: "animal-care";
+    active: false;
+    maxDevices: 2;
+}>)[];
+/** Public ledger fixture: no clear contact or tenant-local employee UUID. */
+export declare const EXAMPLE_ORGANIZATION_ROLE_LICENSE: OrganizationRoleLicense;

package/dist/examples/organization-role-license.js

@@ -0,0 +1,37 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { buildStableActorIdentifier } from '../utils/actor-identifier.js';
+import { buildOrganizationRoleLicenseId, } from '../utils/organization-role-license.js';
+/** Reusable synthetic identity for role-licence contract and consumer tests. */
+export const EXAMPLE_ORGANIZATION_ROLE_LICENSE_IDENTITY = Object.freeze({
+    jurisdiction: 'es',
+    organizationId: 'urn:org:TAX:ES-B12345678',
+    stableContactIdentifier: buildStableActorIdentifier({
+        contactKind: 'email',
+        contact: 'professional@example.org',
+    }),
+    licensedRole: 'RESPRSN',
+});
+/** Reusable catch-all plus exact-override policy example. */
+export const EXAMPLE_ORGANIZATION_ROLE_LICENSE_POLICIES = Object.freeze([
+    Object.freeze({ sector: '', active: true, maxDevices: null }),
+    Object.freeze({ sector: 'animal-care', active: false, maxDevices: 2 }),
+]);
+/** Public ledger fixture: no clear contact or tenant-local employee UUID. */
+export const EXAMPLE_ORGANIZATION_ROLE_LICENSE = Object.freeze({
+    id: buildOrganizationRoleLicenseId(EXAMPLE_ORGANIZATION_ROLE_LICENSE_IDENTITY),
+    ...EXAMPLE_ORGANIZATION_ROLE_LICENSE_IDENTITY,
+    status: 'active',
+    data: [...EXAMPLE_ORGANIZATION_ROLE_LICENSE_POLICIES],
+    devices: [
+        Object.freeze({
+            clientId: 'example-client-health-1',
+            clientInstanceId: 'example-installation-health-1',
+            sector: 'health-care',
+            host: 'https://gw.example.org',
+            status: 'active',
+            activatedAt: 1_700_000_000,
+        }),
+    ],
+    createdAt: 1_700_000_000,
+    updatedAt: 1_700_000_000,
+});

package/dist/models/index.d.ts

@@ -19,6 +19,7 @@ export * from './dataspace-discovery';
 export * from './dataspace-discovery-defaults';
 export * from './dataspace-protocol';
 export * from './device-license';
+export * from './organization-role-license';
 export * from './organization-employee-lifecycle';
 export * from './did';
 export * from './fhir-documents';

package/dist/models/index.js

@@ -19,6 +19,7 @@ export * from './dataspace-discovery.js';
 export * from './dataspace-discovery-defaults.js';
 export * from './dataspace-protocol.js';
 export * from './device-license.js';
+export * from './organization-role-license.js';
 export * from './organization-employee-lifecycle.js';
 export * from './did.js';
 export * from './fhir-documents.js';

package/dist/models/organization-role-license.d.ts

@@ -0,0 +1,45 @@
+import type { DeviceBindingStatus } from '../constants/device';
+/** Lifecycle of one organization-owned, role-bearing licence assignment. */
+export type OrganizationRoleLicenseStatus = 'active' | 'revoked';
+/**
+ * Contractual policy for one sector.
+ *
+ * `sector: ""` is the catch-all policy. An exact sector entry overrides it.
+ * `maxDevices: null` delegates the numeric limit to the GW/portal policy; it
+ * does not mean an unlimited number of installations.
+ */
+export interface OrganizationRoleLicenseSectorPolicy {
+    sector: string;
+    active: boolean;
+    maxDevices: number | null;
+}
+/** One concrete DCR installation registered against the licence. */
+export interface OrganizationRoleLicenseDevice {
+    clientId: string;
+    clientInstanceId: string;
+    sector: string;
+    host: string;
+    status: DeviceBindingStatus;
+    activatedAt: number;
+    revokedAt?: number;
+}
+/**
+ * Public ledger projection of one licence assigned by an organization.
+ *
+ * The stable contact is a one-way `urn:multibase:` identifier. Clear email,
+ * telephone, tenant-local employee UUIDs, payment details and application
+ * permissions must never be written to this asset.
+ */
+export interface OrganizationRoleLicense {
+    id: string;
+    organizationId: string;
+    jurisdiction: string;
+    stableContactIdentifier: string;
+    licensedRole: string;
+    status: OrganizationRoleLicenseStatus;
+    data: OrganizationRoleLicenseSectorPolicy[];
+    devices: OrganizationRoleLicenseDevice[];
+    createdAt: number;
+    updatedAt: number;
+    revokedAt?: number;
+}

package/dist/models/organization-role-license.js

@@ -0,0 +1,2 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export {};

package/dist/utils/index.d.ts

@@ -88,6 +88,7 @@ export * from './organization-test-network-credential';
 export * from './test-network-organization-credentials';
 export * from './local-terminology-provider';
 export * from './license';
+export * from './organization-role-license';
 export * from './license-commercial-search';
 export * from './license-list-search';
 export * from './license-offer-order';

package/dist/utils/index.js

@@ -88,6 +88,7 @@ export * from './organization-test-network-credential.js';
 export * from './test-network-organization-credentials.js';
 export * from './local-terminology-provider.js';
 export * from './license.js';
+export * from './organization-role-license.js';
 export * from './license-commercial-search.js';
 export * from './license-list-search.js';
 export * from './license-offer-order.js';

package/dist/utils/organization-role-license.d.ts

@@ -0,0 +1,41 @@
+import type { OrganizationRoleLicense, OrganizationRoleLicenseDevice, OrganizationRoleLicenseSectorPolicy } from '../models/organization-role-license';
+export type OrganizationRoleLicenseIdentity = Readonly<{
+    jurisdiction: string;
+    organizationId: string;
+    stableContactIdentifier: string;
+    licensedRole: string;
+}>;
+/**
+ * Builds the exact, compact licence preimage agreed across portals and hosts.
+ * The preimage is hashed before persistence and is never itself a ledger key.
+ */
+export declare function buildOrganizationRoleLicensePreimage(identity: OrganizationRoleLicenseIdentity): string;
+/** SHA3-384 multihash identifier for organization + contact + licensed role. */
+export declare function buildOrganizationRoleLicenseId(identity: OrganizationRoleLicenseIdentity): string;
+/** Validates and de-duplicates sector policies while preserving input order. */
+export declare function normalizeOrganizationRoleLicensePolicies(policies: readonly OrganizationRoleLicenseSectorPolicy[]): OrganizationRoleLicenseSectorPolicy[];
+/** Exact sector policy wins; the empty-sector catch-all is only a fallback. */
+export declare function resolveOrganizationRoleLicensePolicy(policies: readonly OrganizationRoleLicenseSectorPolicy[], sector: string): OrganizationRoleLicenseSectorPolicy | undefined;
+/** Returns the contractual limit or the positive GW/portal default. */
+export declare function resolveOrganizationRoleLicenseMaxDevices(policy: OrganizationRoleLicenseSectorPolicy, defaultMaxDevices: number): number;
+/** Checks global status plus the resolved exact/catch-all sector policy. */
+export declare function organizationRoleLicenseAllowsSector(license: Readonly<{
+    status: OrganizationRoleLicense['status'];
+    data: readonly OrganizationRoleLicenseSectorPolicy[];
+}>, sector: string): boolean;
+/** Active DCR installations are counted per concrete sector, across hosts/apps. */
+export declare function countActiveOrganizationRoleLicenseDevices(devices: readonly OrganizationRoleLicenseDevice[], sector: string): number;
+/**
+ * Deterministic DCR admission decision. Re-registering the same active client
+ * is idempotent and does not consume an additional device slot.
+ */
+export declare function organizationRoleLicenseAllowsDevice(license: Readonly<{
+    status: OrganizationRoleLicense['status'];
+    data: readonly OrganizationRoleLicenseSectorPolicy[];
+    devices: readonly OrganizationRoleLicenseDevice[];
+}>, input: Readonly<{
+    sector: string;
+    clientId: string;
+    clientInstanceId: string;
+    defaultMaxDevices: number;
+}>): boolean;

package/dist/utils/organization-role-license.js

@@ -0,0 +1,99 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { encodeMultibaseSha3 } from './multibasehash.js';
+function required(value, label) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new TypeError(`${label} is required.`);
+    return normalized;
+}
+function normalizedSector(value) {
+    return String(value || '').trim().toLowerCase();
+}
+function validateStableContactIdentifier(value) {
+    const normalized = required(value, 'stableContactIdentifier');
+    if (!/^urn:multibase:z[1-9A-HJ-NP-Za-km-z]+$/.test(normalized)) {
+        throw new TypeError('stableContactIdentifier must be a canonical urn:multibase value.');
+    }
+    return normalized;
+}
+/**
+ * Builds the exact, compact licence preimage agreed across portals and hosts.
+ * The preimage is hashed before persistence and is never itself a ledger key.
+ */
+export function buildOrganizationRoleLicensePreimage(identity) {
+    const jurisdiction = required(identity.jurisdiction, 'jurisdiction').toLowerCase();
+    const organizationId = required(identity.organizationId, 'organizationId');
+    const stableContactIdentifier = validateStableContactIdentifier(identity.stableContactIdentifier);
+    const licensedRole = required(identity.licensedRole, 'licensedRole');
+    return `urn:cds-${jurisdiction}:${organizationId}:${stableContactIdentifier}:${licensedRole}`;
+}
+/** SHA3-384 multihash identifier for organization + contact + licensed role. */
+export function buildOrganizationRoleLicenseId(identity) {
+    return `urn:multibase:${encodeMultibaseSha3(buildOrganizationRoleLicensePreimage(identity), 384)}`;
+}
+/** Validates and de-duplicates sector policies while preserving input order. */
+export function normalizeOrganizationRoleLicensePolicies(policies) {
+    if (!Array.isArray(policies) || policies.length === 0) {
+        throw new TypeError('At least one licence sector policy is required.');
+    }
+    const seen = new Set();
+    return policies.map((policy) => {
+        const sector = normalizedSector(policy.sector);
+        if (seen.has(sector))
+            throw new TypeError(`Duplicate licence sector policy: ${sector || '<all>'}.`);
+        seen.add(sector);
+        if (policy.maxDevices !== null
+            && (!Number.isInteger(policy.maxDevices) || policy.maxDevices < 1)) {
+            throw new TypeError('maxDevices must be null or a positive integer.');
+        }
+        return { sector, active: Boolean(policy.active), maxDevices: policy.maxDevices };
+    });
+}
+/** Exact sector policy wins; the empty-sector catch-all is only a fallback. */
+export function resolveOrganizationRoleLicensePolicy(policies, sector) {
+    const requested = required(sector, 'sector').toLowerCase();
+    return policies.find((policy) => normalizedSector(policy.sector) === requested)
+        ?? policies.find((policy) => normalizedSector(policy.sector) === '');
+}
+/** Returns the contractual limit or the positive GW/portal default. */
+export function resolveOrganizationRoleLicenseMaxDevices(policy, defaultMaxDevices) {
+    if (policy.maxDevices !== null)
+        return policy.maxDevices;
+    if (!Number.isInteger(defaultMaxDevices) || defaultMaxDevices < 1) {
+        throw new TypeError('defaultMaxDevices must be a positive integer.');
+    }
+    return defaultMaxDevices;
+}
+/** Checks global status plus the resolved exact/catch-all sector policy. */
+export function organizationRoleLicenseAllowsSector(license, sector) {
+    if (license.status !== 'active')
+        return false;
+    return resolveOrganizationRoleLicensePolicy(license.data, sector)?.active === true;
+}
+/** Active DCR installations are counted per concrete sector, across hosts/apps. */
+export function countActiveOrganizationRoleLicenseDevices(devices, sector) {
+    const requested = required(sector, 'sector').toLowerCase();
+    return devices.filter((device) => device.status === 'active'
+        && normalizedSector(device.sector) === requested).length;
+}
+/**
+ * Deterministic DCR admission decision. Re-registering the same active client
+ * is idempotent and does not consume an additional device slot.
+ */
+export function organizationRoleLicenseAllowsDevice(license, input) {
+    const sector = required(input.sector, 'sector').toLowerCase();
+    const clientId = required(input.clientId, 'clientId');
+    const clientInstanceId = required(input.clientInstanceId, 'clientInstanceId');
+    if (!organizationRoleLicenseAllowsSector(license, sector))
+        return false;
+    if (license.devices.some((device) => device.status === 'active'
+        && device.clientId === clientId
+        && device.clientInstanceId === clientInstanceId
+        && normalizedSector(device.sector) === sector))
+        return true;
+    const policy = resolveOrganizationRoleLicensePolicy(license.data, sector);
+    if (!policy)
+        return false;
+    return countActiveOrganizationRoleLicenseDevices(license.devices, sector)
+        < resolveOrganizationRoleLicenseMaxDevices(policy, input.defaultMaxDevices);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.5.11",
+  "version": "2.5.12",
   "publishConfig": {
     "access": "public"
   },