gdc-common-utils-ts 2.4.0 → 2.4.1

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

@@ -161,7 +161,11 @@ export interface DeviceLicense {
     maxDevices?: number;
     /** All DCR installations bound to this user/member seat. */
     deviceBindings?: DeviceBinding[];
-    /** Identity-provider subject that first activated this seat. */
+    /**
+     * 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.

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/package.json

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