gdc-common-utils-ts 1.7.0 → 1.8.0

package/README.md

@@ -131,6 +131,8 @@ The canonical API contract should live in JSDoc on exported code. The README act
 ### Communication / document utilities
 
 - [`initializeCommunicationIdentity(...)`](src/utils/communication-identity.ts)
+  - bootstraps the technical communication profile identity for a device/app/channel runtime
+  - do not teach its `entityId` as if it were the legal organization id
   - Derives the technical ML-DSA/ML-KEM communication identity for a device, portal, or app profile and returns JOSE header templates for `meta.jws.protected` and `meta.jwe.header`.
   - Uses explicit `seedMaterial` for deterministic derivation. Without `seedMaterial`, it defaults to random generation. `mode = deterministic` requires `seedMaterial`.
 - [`buildOrganizationDidWeb(...)`, `buildProfessionalDidWeb(...)`, `buildIndividualDidWeb(...)`](src/utils/did.ts)
@@ -208,7 +210,7 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - Shared route contexts, controller binding fragments, and reusable helper builders.
   - `tenantId` is modeled as an identifier-like route token (`acme-id`), not as a friendly alternate name.
 - [`docs/LIFECYCLE_101.md`](docs/LIFECYCLE_101.md)
-  - Copy/paste lifecycle guide "for torpes" with semantic rules and reusable placeholders.
+  - Copy/paste lifecycle `101` guide with semantic rules and reusable placeholders.
 
 ## Documentation Naming Rules
 

package/dist/constants/actor-session.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Canonical actor-kind vocabulary shared across SDK packages.
+ */
+export declare const ActorKinds: Readonly<{
+    readonly HostOnboarding: "host_onboarding";
+    readonly OrganizationController: "organization_controller";
+    readonly OrganizationEmployee: "organization_employee";
+    readonly IndividualController: "individual_controller";
+    readonly IndividualMember: "individual_member";
+    readonly Professional: "professional";
+}>;
+/**
+ * Canonical capability vocabulary shared across SDK packages.
+ */
+export declare const ActorCapabilities: Readonly<{
+    readonly HostActivateOrganization: "host.activate_organization";
+    readonly HostConfirmOrder: "host.confirm_order";
+    readonly OrganizationCreateEmployee: "organization.create_employee";
+    readonly OrganizationDisableEmployee: "organization.disable_employee";
+    readonly OrganizationPurgeEmployee: "organization.purge_employee";
+    readonly OrganizationActivateDevice: "organization.activate_device";
+    readonly OrganizationIssueActivationCode: "organization.issue_activation_code";
+    readonly OrganizationRequestSmartToken: "organization.request_smart_token";
+    readonly IndividualBootstrap: "individual.bootstrap";
+    readonly IndividualDisable: "individual.disable";
+    readonly IndividualPurge: "individual.purge";
+    readonly IndividualImportIps: "individual.import_ips";
+    readonly IndividualGenerateDigitalTwin: "individual.generate_digital_twin";
+    readonly IndividualIngestCommunication: "individual.ingest_communication";
+    readonly IndividualUpsertRelatedPerson: "individual.upsert_related_person";
+    readonly IndividualMemberDisable: "individual_member.disable";
+    readonly IndividualMemberPurge: "individual_member.purge";
+    readonly ConsentGrantProfessionalAccess: "consent.grant_professional_access";
+    readonly ProfessionalMedication: "professional.medication";
+    readonly ProfessionalAppointment: "professional.appointment";
+    readonly ProfessionalRequestSmartToken: "professional.request_smart_token";
+    readonly TokenRequestSmart: "token.request_smart";
+}>;
+export type ActorKindsValue = typeof ActorKinds[keyof typeof ActorKinds];
+export type ActorCapabilitiesValue = typeof ActorCapabilities[keyof typeof ActorCapabilities];

package/dist/constants/actor-session.js

@@ -0,0 +1,40 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+/**
+ * Canonical actor-kind vocabulary shared across SDK packages.
+ */
+export const ActorKinds = Object.freeze({
+    HostOnboarding: 'host_onboarding',
+    OrganizationController: 'organization_controller',
+    OrganizationEmployee: 'organization_employee',
+    IndividualController: 'individual_controller',
+    IndividualMember: 'individual_member',
+    Professional: 'professional',
+});
+/**
+ * Canonical capability vocabulary shared across SDK packages.
+ */
+export const ActorCapabilities = Object.freeze({
+    HostActivateOrganization: 'host.activate_organization',
+    HostConfirmOrder: 'host.confirm_order',
+    OrganizationCreateEmployee: 'organization.create_employee',
+    OrganizationDisableEmployee: 'organization.disable_employee',
+    OrganizationPurgeEmployee: 'organization.purge_employee',
+    OrganizationActivateDevice: 'organization.activate_device',
+    OrganizationIssueActivationCode: 'organization.issue_activation_code',
+    OrganizationRequestSmartToken: 'organization.request_smart_token',
+    IndividualBootstrap: 'individual.bootstrap',
+    IndividualDisable: 'individual.disable',
+    IndividualPurge: 'individual.purge',
+    IndividualImportIps: 'individual.import_ips',
+    IndividualGenerateDigitalTwin: 'individual.generate_digital_twin',
+    IndividualIngestCommunication: 'individual.ingest_communication',
+    IndividualUpsertRelatedPerson: 'individual.upsert_related_person',
+    IndividualMemberDisable: 'individual_member.disable',
+    IndividualMemberPurge: 'individual_member.purge',
+    ConsentGrantProfessionalAccess: 'consent.grant_professional_access',
+    ProfessionalMedication: 'professional.medication',
+    ProfessionalAppointment: 'professional.appointment',
+    ProfessionalRequestSmartToken: 'professional.request_smart_token',
+    TokenRequestSmart: 'token.request_smart',
+});

package/dist/constants/index.d.ts

@@ -1,3 +1,4 @@
+export * from './actor-session';
 export * from './communication';
 export * from './cryptography';
 export * from './device';

package/dist/constants/index.js

@@ -1,3 +1,4 @@
+export * from './actor-session.js';
 export * from './communication.js';
 export * from './cryptography.js';
 export * from './device.js';

package/dist/models/actor-session.d.ts

@@ -0,0 +1,9 @@
+import type { ActorCapabilitiesValue, ActorKindsValue } from '../constants/actor-session';
+/**
+ * Canonical actor kind shared across SDK packages.
+ */
+export type ActorKind = ActorKindsValue;
+/**
+ * Canonical capability token shared across SDK packages.
+ */
+export type Capability = ActorCapabilitiesValue;

package/dist/models/actor-session.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+export {};

package/dist/models/did.d.ts

@@ -1,6 +1,8 @@
 import { PublicJwk } from "../interfaces/Cryptography.types";
 import { RecipientPublicKey } from "./crypto";
 import { JwkSet } from "./jwk";
+import type { ActorKind } from "./actor-session";
+export type { ActorKind } from "./actor-session";
 /**
  * The parameters required to construct a service endpoint selector.
  * This is the contract for a specific API method to define its endpoint.
@@ -71,7 +73,6 @@ export interface VerificationMethod extends RecipientPublicKey {
     controller: string;
     publicKeyJwk: PublicJwk;
 }
-export type ActorKind = 'host_onboarding' | 'organization_controller' | 'organization_employee' | 'individual_controller' | 'individual_member' | 'professional';
 export interface ResolvedServiceEndpoint {
     id: string;
     type: string;

package/dist/models/index.d.ts

@@ -1,3 +1,4 @@
+export * from './actor-session';
 export * from './aes';
 export * from './auth';
 export * from './bundle';

package/dist/models/index.js

@@ -1,3 +1,4 @@
+export * from './actor-session.js';
 export * from './aes.js';
 export * from './auth.js';
 export * from './bundle.js';

package/dist/utils/communication-identity.d.ts

@@ -6,9 +6,21 @@ import { JwkKeyUses } from '../constants/cryptography';
 export type CommunicationIdentityBootstrapMode = 'deterministic' | 'random';
 export interface CommunicationIdentityBootstrapOptions {
     /**
-     * Stable logical identifier of the device/profile/app bootstrap context.
+     * Stable logical identifier of the technical communication profile.
      *
-     * This is metadata for the caller. It is not used as implicit seed material.
+     * This is not the legal organization id, not the tenant id, and not the
+     * human controller identity.
+     *
+     * Treat it as the id of the technical channel/runtime/device profile that
+     * owns the communication keys for this app/service.
+     *
+     * Good examples:
+     * - `portal.acme.org:acme-id:web-channel`
+     * - `portal.acme.org:acme-id:backend-runtime`
+     * - `mobile.acme.app:user-42:device-primary`
+     *
+     * This value is metadata for the caller. It is not used as implicit seed
+     * material.
      */
     entityId: string;
     /**
@@ -114,10 +126,17 @@ export interface CommunicationIdentityBootstrapResult {
  * human/person signing identity used for controller/professional/individual
  * authorization decisions.
  *
+ * Conceptual split:
+ * - `appId` identifies the application towards GW CORE headers/policy
+ * - `entityId` identifies the local technical communication profile that owns
+ *   transport keys
+ * - controller/professional/subject DIDs identify domain actors
+ *
  * The returned JOSE header templates match the current DIDComm metadata contract:
  * `meta.jws.protected` and `meta.jwe.header`.
  *
- * @param options.entityId Stable logical identity of the bootstrap context.
+ * @param options.entityId Stable logical identity of the technical
+ * communication profile or channel runtime.
  * @param options.seedMaterial Explicit seed material for deterministic derivation.
  * @param options.cryptography Stateless crypto engine implementation.
  * @param options.mode Deterministic or random seed derivation mode.

package/dist/utils/communication-identity.js

@@ -11,10 +11,17 @@ import { CommunicationKeyPurposes, DefaultEncryptionCurves, DefaultSigningAlgori
  * human/person signing identity used for controller/professional/individual
  * authorization decisions.
  *
+ * Conceptual split:
+ * - `appId` identifies the application towards GW CORE headers/policy
+ * - `entityId` identifies the local technical communication profile that owns
+ *   transport keys
+ * - controller/professional/subject DIDs identify domain actors
+ *
  * The returned JOSE header templates match the current DIDComm metadata contract:
  * `meta.jws.protected` and `meta.jwe.header`.
  *
- * @param options.entityId Stable logical identity of the bootstrap context.
+ * @param options.entityId Stable logical identity of the technical
+ * communication profile or channel runtime.
  * @param options.seedMaterial Explicit seed material for deterministic derivation.
  * @param options.cryptography Stateless crypto engine implementation.
  * @param options.mode Deterministic or random seed derivation mode.

package/dist/utils/did-resolution.d.ts

@@ -1,4 +1,5 @@
-import { ActorKind, DidDocument, DidResolutionResult, ResolvedServiceEndpoint } from '../models/did';
+import type { ActorKind } from '../models/actor-session';
+import { DidDocument, DidResolutionResult, ResolvedServiceEndpoint } from '../models/did';
 /**
  * Service selection criteria used when resolving operational endpoints from a DID Document.
  */

package/dist/utils/did-resolution.js

@@ -1,4 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { ActorKinds } from '../constants/actor-session.js';
 import { DiscoveryCapabilities, DidServiceIds } from '../constants/did-services.js';
 function normalizeServiceEndpoint(service) {
     const capability = inferCapabilityFromServiceId(service.id)
@@ -147,16 +148,16 @@ export function getActorKindFromDid(did) {
         return 'unknown';
     if (normalized.includes(':employee:')) {
         return normalized.includes('resprsn') || normalized.includes('controller')
-            ? 'organization_controller'
-            : 'professional';
+            ? ActorKinds.OrganizationController
+            : ActorKinds.Professional;
     }
     if (normalized.includes(':family:') || normalized.includes(':member:')) {
         return normalized.includes('oneself') || normalized.includes('controller')
-            ? 'individual_controller'
-            : 'individual_member';
+            ? ActorKinds.IndividualController
+            : ActorKinds.IndividualMember;
     }
     if (normalized.includes('host'))
-        return 'host_onboarding';
+        return ActorKinds.HostOnboarding;
     return 'unknown';
 }
 /**

package/package.json

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