gdc-common-utils-ts 2.3.29 → 2.4.1

package/dist/models/device-license.d.ts

@@ -17,6 +17,19 @@ export interface DeviceInfo {
     /** The model of the device (e.g., "iPhone14,6"). */
     model?: string;
 }
+/** One concrete DCR client/application installation bound to a licensed seat. */
+export interface DeviceBinding {
+    /** Authorization-server assigned DCR client identifier. */
+    clientId: string;
+    /** Stable application installation fingerprint supplied by the client. */
+    clientInstanceId: string;
+    /** Current relationship between this installation and the seat. */
+    status: 'active' | 'revoked';
+    /** Device/application metadata captured during DCR. */
+    deviceInfo: DeviceInfo;
+    activatedAt: number;
+    revokedAt?: number;
+}
 /**
  * A set of rules that a device must match to be eligible to activate a license.
  */
@@ -141,6 +154,19 @@ export interface DeviceLicense {
      * Populated when the status becomes 'active'.
      */
     deviceId?: string;
+    /**
+     * Maximum number of simultaneously active DCR installations for this seat.
+     * Defaults to two when omitted for legacy records.
+     */
+    maxDevices?: number;
+    /** All DCR installations bound to this user/member seat. */
+    deviceBindings?: DeviceBinding[];
+    /**
+     * Stable private actor identifier:
+     * `urn:multibase:<hash(normalized email or phone)>:<professional|personal>`.
+     * Portal DIDs, IdP subjects, wallets and DCR clients bind to this value but do not define it.
+     */
+    activatedBy?: string;
     /**
      * Optional, pre-defined restrictions on which devices are allowed to activate this license.
      * Set at the time of license creation.

package/dist/models/fhir-r5-subscription.d.ts

@@ -0,0 +1,123 @@
+/** Standard FHIR R5 Subscription channel coding. */
+export declare const FhirR5SubscriptionChannelTypes: Readonly<{
+    readonly RestHook: "rest-hook";
+}>;
+export declare const FhirR5SubscriptionScopes: Readonly<{
+    readonly Individual: "individual";
+    readonly Tenant: "tenant";
+}>;
+export type FhirR5SubscriptionScope = typeof FhirR5SubscriptionScopes[keyof typeof FhirR5SubscriptionScopes];
+export interface FhirR5SubscriptionFilter {
+    resourceType?: string;
+    filterParameter: string;
+    comparator?: 'eq' | 'ne';
+    modifier?: string;
+    value: string;
+}
+export interface FhirR5Subscription {
+    resourceType: 'Subscription';
+    id: string;
+    status: 'requested' | 'active' | 'error' | 'off' | 'entered-in-error';
+    topic: string;
+    reason?: string;
+    filterBy?: FhirR5SubscriptionFilter[];
+    channelType: {
+        system?: string;
+        code: string;
+    };
+    endpoint?: string;
+    parameter?: Array<{
+        name: string;
+        value: string;
+    }>;
+    contentType?: string;
+    content?: 'empty' | 'id-only' | 'full-resource';
+    heartbeatPeriod?: number;
+    timeout?: number;
+    maxCount?: number;
+}
+export interface FhirR5SubscriptionTopicFilterDefinition {
+    resourceType?: string;
+    filterParameter: string;
+    comparator?: Array<'eq' | 'ne'>;
+    modifier?: string[];
+}
+export interface FhirR5SubscriptionTopic {
+    resourceType: 'SubscriptionTopic';
+    id: string;
+    url: string;
+    status: 'draft' | 'active' | 'retired' | 'unknown';
+    title?: string;
+    description?: string;
+    resourceTrigger: Array<{
+        resource: string;
+    }>;
+    canFilterBy?: FhirR5SubscriptionTopicFilterDefinition[];
+}
+export interface BuildFhirR5RestHookSubscriptionInput {
+    id: string;
+    scope: FhirR5SubscriptionScope;
+    topic: string;
+    endpoint: string;
+    filters?: readonly FhirR5SubscriptionFilter[];
+    reason?: string;
+    contentType?: string;
+    heartbeatPeriod?: number;
+    timeout?: number;
+}
+/** Builds a reusable standards-shaped FHIR R5 rest-hook Subscription. */
+export declare function buildFhirR5RestHookSubscription(input: BuildFhirR5RestHookSubscriptionInput): FhirR5Subscription;
+/** Builds the relative gateway `_batch` request for a Subscription resource. */
+export declare function buildFhirR5SubscriptionBatch(subscription: FhirR5Subscription, scope: FhirR5SubscriptionScope): {
+    path: string;
+    body: {
+        resourceType: "Bundle";
+        type: "batch";
+        entry: {
+            request: {
+                method: "POST";
+                url: "Subscription";
+            };
+            resource: FhirR5Subscription;
+        }[];
+    };
+};
+/** Builds the standard R5 notification Bundle delivered to a subscriber. */
+export declare function buildFhirR5SubscriptionNotification(input: {
+    subscriptionReference: string;
+    topic?: string;
+    eventNumber: number;
+    focusReference: string;
+    eventsSinceSubscriptionStart: number;
+    timestamp?: string;
+    additionalContextReferences?: readonly string[];
+}): {
+    resourceType: "Bundle";
+    type: "subscription-notification";
+    timestamp: string;
+    entry: {
+        fullUrl: string;
+        resource: {
+            eventsSinceSubscriptionStart: string;
+            notificationEvent: {
+                additionalContext?: {
+                    reference: string;
+                }[] | undefined;
+                eventNumber: string;
+                timestamp: string;
+                focus: {
+                    reference: string;
+                };
+            }[];
+            topic?: string | undefined;
+            resourceType: "SubscriptionStatus";
+            status: "active";
+            type: "event-notification";
+            subscription: {
+                reference: string;
+            };
+        };
+    }[];
+};
+/** Evaluates the initial portable `eq`/`ne` SubscriptionTopic filter profile. */
+export declare function matchesFhirR5SubscriptionEvent(subscription: FhirR5Subscription, topic: FhirR5SubscriptionTopic, resource: Record<string, any>): boolean;

package/dist/models/fhir-r5-subscription.js

@@ -0,0 +1,138 @@
+/** Standard FHIR R5 Subscription channel coding. */
+export const FhirR5SubscriptionChannelTypes = Object.freeze({ RestHook: 'rest-hook' });
+export const FhirR5SubscriptionScopes = Object.freeze({
+    Individual: 'individual',
+    Tenant: 'tenant',
+});
+function requiredText(value, label) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}
+function absoluteHttpsUrl(value, label) {
+    const normalized = requiredText(value, label);
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        throw new Error(`${label} must be an absolute HTTPS URL.`);
+    }
+    if (parsed.protocol !== 'https:')
+        throw new Error(`${label} must be an absolute HTTPS URL.`);
+    return parsed.href;
+}
+/** Builds a reusable standards-shaped FHIR R5 rest-hook Subscription. */
+export function buildFhirR5RestHookSubscription(input) {
+    const filters = (input.filters || []).map((filter) => ({
+        ...(filter.resourceType ? { resourceType: requiredText(filter.resourceType, 'Subscription filter resourceType') } : {}),
+        filterParameter: requiredText(filter.filterParameter, 'Subscription filter parameter'),
+        ...(filter.comparator ? { comparator: filter.comparator } : {}),
+        ...(filter.modifier ? { modifier: filter.modifier } : {}),
+        value: requiredText(filter.value, 'Subscription filter value'),
+    }));
+    if (input.scope === FhirR5SubscriptionScopes.Individual) {
+        const exactSubject = filters.some((filter) => ['patient', 'subject'].includes(filter.filterParameter.toLowerCase())
+            && !filter.value.includes('*') && !filter.value.includes(','));
+        if (!exactSubject)
+            throw new Error('An individual-scoped Subscription requires an exact patient or subject filter.');
+    }
+    return {
+        resourceType: 'Subscription',
+        id: requiredText(input.id, 'Subscription id'),
+        status: 'requested',
+        topic: absoluteHttpsUrl(input.topic, 'Subscription topic'),
+        reason: input.reason?.trim() || 'Notify the registered BFF when matching data changes.',
+        ...(filters.length ? { filterBy: filters } : {}),
+        channelType: {
+            system: 'http://terminology.hl7.org/CodeSystem/subscription-channel-type',
+            code: FhirR5SubscriptionChannelTypes.RestHook,
+        },
+        endpoint: absoluteHttpsUrl(input.endpoint, 'Subscription endpoint'),
+        contentType: input.contentType?.trim() || 'application/fhir+json',
+        content: 'id-only',
+        ...(input.heartbeatPeriod !== undefined ? { heartbeatPeriod: input.heartbeatPeriod } : {}),
+        ...(input.timeout !== undefined ? { timeout: input.timeout } : {}),
+    };
+}
+/** Builds the relative gateway `_batch` request for a Subscription resource. */
+export function buildFhirR5SubscriptionBatch(subscription, scope) {
+    const section = scope === FhirR5SubscriptionScopes.Individual ? 'individual' : 'entity';
+    return {
+        path: `${section}/org.hl7.fhir.r5/Subscription/_batch`,
+        body: {
+            resourceType: 'Bundle',
+            type: 'batch',
+            entry: [{ request: { method: 'POST', url: 'Subscription' }, resource: subscription }],
+        },
+    };
+}
+/** Builds the standard R5 notification Bundle delivered to a subscriber. */
+export function buildFhirR5SubscriptionNotification(input) {
+    const timestamp = input.timestamp || new Date().toISOString();
+    return {
+        resourceType: 'Bundle',
+        type: 'subscription-notification',
+        timestamp,
+        entry: [{
+                fullUrl: 'urn:uuid:subscription-status',
+                resource: {
+                    resourceType: 'SubscriptionStatus',
+                    status: 'active',
+                    type: 'event-notification',
+                    subscription: { reference: requiredText(input.subscriptionReference, 'Subscription reference') },
+                    ...(input.topic ? { topic: input.topic } : {}),
+                    eventsSinceSubscriptionStart: String(input.eventsSinceSubscriptionStart),
+                    notificationEvent: [{
+                            eventNumber: String(input.eventNumber),
+                            timestamp,
+                            focus: { reference: requiredText(input.focusReference, 'Notification focus reference') },
+                            ...(input.additionalContextReferences?.length ? {
+                                additionalContext: input.additionalContextReferences.map((reference) => ({ reference })),
+                            } : {}),
+                        }],
+                },
+            }],
+    };
+}
+function readPath(resource, path) {
+    const aliases = {
+        patient: ['patient.reference', 'subject.reference'],
+        subject: ['subject.reference', 'patient.reference'],
+    };
+    const paths = aliases[path.toLowerCase()] || [path];
+    const values = [];
+    for (const candidate of paths) {
+        let current = [resource];
+        for (const part of candidate.split('.')) {
+            current = current.flatMap((value) => {
+                const next = value?.[part];
+                return Array.isArray(next) ? next : next === undefined ? [] : [next];
+            });
+        }
+        values.push(...current.map((value) => String(value)).filter(Boolean));
+    }
+    return values;
+}
+/** Evaluates the initial portable `eq`/`ne` SubscriptionTopic filter profile. */
+export function matchesFhirR5SubscriptionEvent(subscription, topic, resource) {
+    if (subscription.status !== 'active' || topic.status !== 'active' || subscription.topic !== topic.url)
+        return false;
+    const resourceType = String(resource.resourceType || '');
+    if (!topic.resourceTrigger.some((trigger) => trigger.resource === resourceType))
+        return false;
+    return (subscription.filterBy || []).every((filter) => {
+        if (filter.resourceType && filter.resourceType !== resourceType)
+            return true;
+        const allowed = (topic.canFilterBy || []).find((candidate) => candidate.filterParameter === filter.filterParameter
+            && (!candidate.resourceType || candidate.resourceType === resourceType));
+        if (!allowed)
+            return false;
+        const comparator = filter.comparator || 'eq';
+        if (allowed.comparator?.length && !allowed.comparator.includes(comparator))
+            return false;
+        const match = readPath(resource, filter.filterParameter).includes(filter.value);
+        return comparator === 'ne' ? !match : match;
+    });
+}

package/dist/models/index.d.ts

@@ -41,6 +41,7 @@ export * from './oidc4ida.document.model';
 export * from './oidc4ida.electronicRecord.model';
 export * from './oidc4ida.evidence.model';
 export * from './openid-device';
+export * from './fhir-r5-subscription';
 export * from './permission-templates';
 export * from './profile-manager';
 export * from './operation-outcome';

package/dist/models/index.js

@@ -41,6 +41,7 @@ export * from './oidc4ida.document.model.js';
 export * from './oidc4ida.electronicRecord.model.js';
 export * from './oidc4ida.evidence.model.js';
 export * from './openid-device.js';
+export * from './fhir-r5-subscription.js';
 export * from './permission-templates.js';
 export * from './profile-manager.js';
 export * from './operation-outcome.js';

package/dist/models/openid-device.d.ts

@@ -13,12 +13,12 @@ export interface OpenIdDeviceInfo {
      * The push notification token for the device.
      * @example "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
      */
-    push_token: string;
+    push_token?: string;
     /**
      * The push notification provider.
      * @example "expo"
      */
-    push_provider: string;
+    push_provider?: string;
     /**
      * A unique identifier for the device, such as the OS internal build ID.
      * @example "19.6.0"
@@ -44,9 +44,19 @@ export interface DcrRegistrationRequest {
      */
     redirect_uris: string[];
     /**
-     * Kind of the application. The only supported value is 'native'.
+     * Kind of the application. Browser/BFF clients use `web`; installed apps use
+     * `native`. This does not identify a concrete browser session or push token.
      */
-    application_type?: 'native';
+    application_type?: 'native' | 'web';
+    /**
+     * Stable identifier assigned by the software publisher. The GDC profile uses
+     * a reverse-DNS value such as `es.globaldatacare.portal`; the authorization
+     * server still assigns a distinct `client_id` to the registration instance.
+     * @see https://www.rfc-editor.org/rfc/rfc7591.html#section-2
+     */
+    software_id?: string;
+    /** Version of the client software identified by `software_id`. */
+    software_version?: string;
     /**
      * Human-readable name of the client to be presented to the end-user.
      * @example "My Awesome App"
@@ -78,6 +88,11 @@ export interface DcrRegistrationRequest {
     jwks?: JwkSet;
     /**
      * Custom data about the specific device instance being registered.
+     *
+     * `push_token` and `push_provider` may bootstrap one delivery endpoint, but
+     * push subscriptions have their own lifecycle and are not the device/client
+     * identity. A client can later maintain several Web Push, APNs or FCM
+     * subscriptions without issuing another professional seat.
      * This is prefixed to avoid collision with standard fields.
      */
     ext_device_info?: OpenIdDeviceInfo;

package/dist/utils/actor-identifier.d.ts

@@ -0,0 +1,36 @@
+/** Cross-portal actor classes. These are intentionally broader than job roles. */
+export declare const StableActorRoles: Readonly<{
+    readonly Professional: "professional";
+    readonly Personal: "personal";
+}>;
+export type StableActorRole = typeof StableActorRoles[keyof typeof StableActorRoles];
+export type StableActorContactKind = 'email' | 'phone';
+/**
+ * Builds the private, stable actor identifier shared by independent portals.
+ *
+ * Wire format: `urn:multibase:<multibase(multihash(SHA3-256, normalized-contact))>:<role>`.
+ * Examples end in `:professional` or `:personal`; the clear email/phone is
+ * never embedded. A portal-specific `did:web`, IdP `sub`, wallet and DCR
+ * `client_id` are bindings to this identifier, not replacements for it.
+ *
+ * Email is trimmed, stripped of `mailto:` and lower-cased. Phone is stripped
+ * of `tel:` and formatting while preserving an E.164 leading `+`.
+ */
+export declare function buildStableActorIdentifier(input: {
+    contactKind: StableActorContactKind;
+    contact: string;
+    role: StableActorRole;
+}): string;
+/**
+ * Builds a portal-specific DID binding that carries the stable actor payload.
+ * The portal root can change while the final actor payload remains identical.
+ */
+export declare function buildPortalActorDidWeb(input: {
+    portalDidWeb: string;
+    actorIdentifier: string;
+}): string;
+/**
+ * Extracts the stable actor URN from a canonical GDC portal actor DID.
+ * This is extraction, not reversal of the contact hash.
+ */
+export declare function stableActorIdentifierFromDidWeb(didWeb: string): string;

package/dist/utils/actor-identifier.js

@@ -0,0 +1,58 @@
+import { normalizePhone } from './consent.js';
+import { multibase58MultihashSha3_256 } from './same-as.js';
+/** Cross-portal actor classes. These are intentionally broader than job roles. */
+export const StableActorRoles = Object.freeze({
+    Professional: 'professional',
+    Personal: 'personal',
+});
+/**
+ * Builds the private, stable actor identifier shared by independent portals.
+ *
+ * Wire format: `urn:multibase:<multibase(multihash(SHA3-256, normalized-contact))>:<role>`.
+ * Examples end in `:professional` or `:personal`; the clear email/phone is
+ * never embedded. A portal-specific `did:web`, IdP `sub`, wallet and DCR
+ * `client_id` are bindings to this identifier, not replacements for it.
+ *
+ * Email is trimmed, stripped of `mailto:` and lower-cased. Phone is stripped
+ * of `tel:` and formatting while preserving an E.164 leading `+`.
+ */
+export function buildStableActorIdentifier(input) {
+    const role = String(input.role || '').trim();
+    if (!Object.values(StableActorRoles).includes(role)) {
+        throw new Error('Stable actor role must be professional or personal.');
+    }
+    const rawContact = String(input.contact || '').trim();
+    const normalizedContact = input.contactKind === 'email'
+        ? rawContact.replace(/^mailto:/i, '').replace(/\s+/g, '').toLowerCase()
+        : normalizePhone(rawContact.replace(/^tel:/i, ''));
+    if (!normalizedContact) {
+        throw new Error(`Stable actor ${input.contactKind} is required.`);
+    }
+    return `urn:multibase:${multibase58MultihashSha3_256(normalizedContact)}:${role}`;
+}
+/**
+ * Builds a portal-specific DID binding that carries the stable actor payload.
+ * The portal root can change while the final actor payload remains identical.
+ */
+export function buildPortalActorDidWeb(input) {
+    const portalDidWeb = String(input.portalDidWeb || '').trim();
+    const match = /^urn:multibase:(z[^:]+):(professional|personal)$/.exec(String(input.actorIdentifier || '').trim());
+    if (!portalDidWeb.startsWith('did:web:')) {
+        throw new Error('Portal actor binding requires a did:web root.');
+    }
+    if (!match) {
+        throw new Error('Portal actor binding requires a stable actor URN.');
+    }
+    return `${portalDidWeb}:actor:multibase:${match[1]}:${match[2]}`;
+}
+/**
+ * Extracts the stable actor URN from a canonical GDC portal actor DID.
+ * This is extraction, not reversal of the contact hash.
+ */
+export function stableActorIdentifierFromDidWeb(didWeb) {
+    const match = /:actor:multibase:(z[^:]+):(professional|personal)(?::|$)/.exec(String(didWeb || '').trim());
+    if (!match) {
+        throw new Error('DID does not contain a canonical GDC actor binding.');
+    }
+    return `urn:multibase:${match[1]}:${match[2]}`;
+}

package/dist/utils/index.d.ts

@@ -104,6 +104,7 @@ export * from './service-act-reasons';
 export * from './same-as';
 export * from './subject-identity-binding';
 export * from './activation-request';
+export * from './actor-identifier';
 export * from './vp-token';
 export * from './vital-sign-day-batch';
 export * from './wallet-mem';

package/dist/utils/index.js

@@ -104,6 +104,7 @@ export * from './service-act-reasons.js';
 export * from './same-as.js';
 export * from './subject-identity-binding.js';
 export * from './activation-request.js';
+export * from './actor-identifier.js';
 export * from './vp-token.js';
 export * from './vital-sign-day-batch.js';
 export * from './wallet-mem.js';

package/dist/utils/license.d.ts

@@ -1,4 +1,16 @@
 import { DeviceAppType, DeviceUserClass } from '../constants/device';
+import type { DeviceBinding, DeviceLicense } from '../models/device-license';
+/** Default simultaneous installation allowance for one professional/member seat. */
+export declare const DEFAULT_LICENSE_DEVICE_ALLOWANCE = 2;
+/** Resolves an explicit positive allowance or the backwards-compatible default. */
+export declare function resolveLicenseDeviceAllowance(license: unknown): number;
+/**
+ * Reads active bindings while projecting the old singular `deviceId` shape as
+ * one binding. This permits a rolling migration without invalidating seats.
+ */
+export declare function listActiveLicenseDeviceBindings(license: Pick<DeviceLicense, 'deviceBindings' | 'deviceId' | 'deviceInfo' | 'activatedAt'>): DeviceBinding[];
+/** True for an idempotent installation or while the seat still has capacity. */
+export declare function canRegisterLicenseDevice(license: Pick<DeviceLicense, 'maxDevices' | 'deviceBindings' | 'deviceId' | 'deviceInfo' | 'activatedAt'>, clientInstanceId: string): boolean;
 export type LicenseClaims = Record<string, unknown>;
 export declare const LicenseClaimContext: Readonly<{
     readonly SchemaOrg: "org.schema";

package/dist/utils/license.js

@@ -1,5 +1,40 @@
 import { DeviceAppTypes, DeviceUserClasses } from '../constants/device.js';
 import { ClaimsIndividualProductSchemaorg, ClaimsOfferSchemaorg, ClaimsPersonSchemaorg, } from '../constants/schemaorg.js';
+/** Default simultaneous installation allowance for one professional/member seat. */
+export const DEFAULT_LICENSE_DEVICE_ALLOWANCE = 2;
+/** Resolves an explicit positive allowance or the backwards-compatible default. */
+export function resolveLicenseDeviceAllowance(license) {
+    const value = Number(license?.maxDevices);
+    return Number.isInteger(value) && value > 0 ? value : DEFAULT_LICENSE_DEVICE_ALLOWANCE;
+}
+/**
+ * Reads active bindings while projecting the old singular `deviceId` shape as
+ * one binding. This permits a rolling migration without invalidating seats.
+ */
+export function listActiveLicenseDeviceBindings(license) {
+    if (Array.isArray(license.deviceBindings)) {
+        return license.deviceBindings.filter((binding) => binding.status === 'active');
+    }
+    const clientId = String(license.deviceId || '').trim();
+    if (!clientId)
+        return [];
+    const deviceInfo = license.deviceInfo || { clientInstanceId: clientId };
+    return [{
+            clientId,
+            clientInstanceId: deviceInfo.clientInstanceId || clientId,
+            status: 'active',
+            deviceInfo,
+            activatedAt: Number(license.activatedAt || 0),
+        }];
+}
+/** True for an idempotent installation or while the seat still has capacity. */
+export function canRegisterLicenseDevice(license, clientInstanceId) {
+    const installationId = String(clientInstanceId || '').trim();
+    const active = listActiveLicenseDeviceBindings(license);
+    if (installationId && active.some((binding) => binding.clientInstanceId === installationId))
+        return true;
+    return active.length < resolveLicenseDeviceAllowance(license);
+}
 export const LicenseClaimContext = Object.freeze({
     SchemaOrg: 'org.schema',
 });

package/package.json

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