@cratis/arc 22.14.2 → 22.15.0

package/identity/IdentityProvider.ts

@@ -1,10 +1,11 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Constructor, JsonSerializer } from '@cratis/fundamentals';
+import { Constructor } from '@cratis/fundamentals';
 import { IIdentityProvider } from './IIdentityProvider';
 import { IIdentity } from './IIdentity';
 import { IdentityProviderResult } from './IdentityProviderResult';
+import { deserializeIdentityDetails } from './deserializeIdentityDetails';
 import { GetHttpHeaders } from '../GetHttpHeaders';
 import { Globals } from '../Globals';
 import { UrlHelpers } from '../UrlHelpers';
@@ -55,7 +56,7 @@ export class IdentityProvider extends IIdentityProvider {
         if (cookie.length == 2) {
             const json = atob(cookie[1]);
             const result = JSON.parse(json) as IdentityProviderResult;
-            const details = type ? JsonSerializer.deserializeFromInstance(type, result.details) : result.details;
+            const details = deserializeIdentityDetails(type, result.details);
             return {
                 id: result.id,
                 name: result.name,
@@ -93,7 +94,7 @@ export class IdentityProvider extends IIdentityProvider {
         }
 
         const result = await response.json() as IdentityProviderResult;
-        const details = type ? JsonSerializer.deserializeFromInstance(type, result.details) : result.details;
+        const details = deserializeIdentityDetails(type, result.details);
 
         return {
             id: result.id,

package/identity/deserializeIdentityDetails.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor, Fields, JsonSerializer } from '@cratis/fundamentals';
+
+/*
+ * ⚠️ deserializeIdentityDetails is exported deliberately, unlike deserializeQueryModel in
+ * ../queries/deserializeQueryModel.ts.
+ *
+ * JsonSerializer's converter registry is module state, and a consumer package can easily resolve a
+ * different physical copy of @cratis/fundamentals than this one - which is why deserializeQueryModel
+ * stays package-private. Identity details are different: @cratis/arc.react's useIdentity() needs to
+ * apply the exact same deserialization as this package's own IdentityProvider, for a payload that may
+ * already be flowing through this package's IdentityProvider/IIdentity. Exporting the function itself
+ * - rather than having @cratis/arc.react re-implement the same logic against its own copy of
+ * @cratis/fundamentals - guarantees every identity details value is deserialized through this one
+ * physical JsonSerializer/Fields, regardless of which package's copy of @cratis/fundamentals the
+ * caller resolved.
+ */
+
+/**
+ * Determines whether a details type is a JavaScript primitive wrapper rather than a real,
+ * `@field`-decorated model.
+ * @param {Constructor} type The details type to check.
+ * @returns {boolean} True when the type is a primitive wrapper.
+ */
+function isPrimitiveDetailsType(type: Constructor): boolean {
+    return type === String || type === Number || type === Boolean;
+}
+
+/**
+ * Deserializes identity details into their strongly-typed shape, guarding every way that doing so
+ * would otherwise crash or silently destroy the payload.
+ * @param {Constructor | undefined} type The details type to deserialize into, or `undefined` to leave
+ * the payload untouched.
+ * @param {unknown} details The raw details payload - parsed JSON from the identity cookie or the
+ * `/.cratis/me` endpoint.
+ * @returns {unknown} The deserialized instance, or `details` unchanged when deserializing it would be
+ * unsafe, pointless, or has already been done.
+ * @remarks
+ * {@link JsonSerializer.deserializeFromInstance} assumes a well-formed object and a target type
+ * carrying `@field` metadata - neither is guaranteed here:
+ * - No type means there is nothing to deserialize into.
+ * - A `null`/`undefined`/non-object payload would make `deserializeFromInstance`'s internal
+ *   `instance[field.name]` lookup throw.
+ * - A payload that is already an instance of the target type has already been deserialized -
+ *   deserializing it again is destructive, not merely wasteful: it can throw on a nested temporal
+ *   value and double-wraps a concept (`{ value: { value: '...' } }`).
+ * - `Object` and the primitive wrapper types (`String`, `Number`, `Boolean`) are not real,
+ *   `@field`-decorated models; deserializing into them would discard the payload.
+ * - A type with no `@field`-decorated members deserializes to an empty instance, silently discarding
+ *   the payload. That is worse than leaving the payload alone, so this warns and passes it through
+ *   instead - preserving data beats a hard crash for anyone upgrading with an undecorated type.
+ */
+export function deserializeIdentityDetails(type: Constructor | undefined, details: unknown): unknown {
+    if (!type || type === Object || isPrimitiveDetailsType(type)) {
+        return details;
+    }
+
+    if (details === null || details === undefined || typeof details !== 'object') {
+        return details;
+    }
+
+    if (details instanceof type) {
+        return details;
+    }
+
+    const fields = Fields.getFieldsForType(type);
+    if (fields.length === 0) {
+        console.warn(
+            `Identity details type '${type.name}' has no @field-decorated members. Deserializing into ` +
+            'it would discard the payload and return an empty instance, so the raw payload is being ' +
+            'passed through instead. Add @field decorators for every property that should be ' +
+            'populated, or omit the details type to receive the raw payload as-is.');
+        return details;
+    }
+
+    return JsonSerializer.deserializeFromInstance(type as Constructor<object>, details);
+}

package/identity/for_IdentityProvider/when_getting_current/with_a_details_type_that_declares_no_fields.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IdentityProvider } from '../../IdentityProvider';
+import { an_identity_provider } from '../given/an_identity_provider';
+import { given } from '../../../given';
+
+// Deliberately undecorated - no @field members. Deserializing into this would construct
+// `new UndecoratedDetails()` and copy nothing, discarding whatever the server sent.
+class UndecoratedDetails {
+    userId!: string;
+    role!: string;
+}
+
+describe('when getting current with a details type that declares no fields', given(an_identity_provider, () => {
+    let originalConsoleWarn: typeof console.warn;
+    let result: { details: UndecoratedDetails };
+
+    beforeEach(async () => {
+        originalConsoleWarn = console.warn;
+        console.warn = () => { /* Suppressed during test */ };
+
+        const identityData = {
+            id: 'test-user-id',
+            name: 'Test User',
+            details: {
+                userId: 'u-1',
+                role: 'admin'
+            }
+        };
+        const encodedData = btoa(JSON.stringify(identityData));
+        (global as { document?: { cookie: string } }).document!.cookie = `.cratis-identity=${encodedData}`;
+
+        const identity = await IdentityProvider.getCurrent(UndecoratedDetails);
+        result = { details: identity.details };
+    });
+
+    afterEach(() => { console.warn = originalConsoleWarn; });
+
+    it('should hand back the payload untouched', () => {
+        (result.details as unknown as { userId: string }).userId.should.equal('u-1');
+        (result.details as unknown as { role: string }).role.should.equal('admin');
+    });
+
+    it('should not blank the details', () => {
+        result.details.should.not.be.instanceOf(UndecoratedDetails);
+    });
+}));

package/identity/for_IdentityProvider/when_getting_current/with_type_safe_details.ts

@@ -1,29 +1,33 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Guid } from '@cratis/fundamentals';
+import { field, Guid } from '@cratis/fundamentals';
 import { IdentityProvider } from '../../IdentityProvider';
 import { an_identity_provider } from '../given/an_identity_provider';
 import { given } from '../../../given';
 
 class TestDetails {
-    userId: Guid = Guid.empty;
-    role: string = '';
+    @field(Guid)
+    userId!: Guid;
+
+    @field(String)
+    role!: string;
 }
 
 describe('when getting current with type safe details', given(an_identity_provider, () => {
     let result: { id: string; name: string; details: TestDetails };
+    let testGuid: Guid;
 
     beforeEach(async () => {
-        const testGuid = Guid.create();
-        
+        testGuid = Guid.create();
+
         // Mock document.cookie with base64-encoded identity data
         const identityData = {
             id: 'test-user-id',
             name: 'Test User',
-            details: { 
-                userId: testGuid.toString(), 
-                role: 'admin' 
+            details: {
+                userId: testGuid.toString(),
+                role: 'admin'
             }
         };
         const encodedData = btoa(JSON.stringify(identityData));
@@ -40,4 +44,9 @@ describe('when getting current with type safe details', given(an_identity_provid
     it('should deserialize details with proper types', () => {
         result.details.userId.should.be.instanceOf(Guid);
     });
+
+    it('should carry over the value the server sent', () => {
+        result.details.userId.toString().should.equal(testGuid.toString());
+        result.details.role.should.equal('admin');
+    });
 }));

package/identity/for_IdentityProvider/when_refreshing/with_type_safe_details.ts

@@ -1,29 +1,33 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Guid } from '@cratis/fundamentals';
+import { field, Guid } from '@cratis/fundamentals';
 import { IdentityProvider } from '../../IdentityProvider';
 import { an_identity_provider } from '../given/an_identity_provider';
 import { given } from '../../../given';
 
 class TestDetails {
-    userId: Guid = Guid.empty;
-    role: string = '';
+    @field(Guid)
+    userId!: Guid;
+
+    @field(String)
+    role!: string;
 }
 
 describe('when refreshing with type safe details', given(an_identity_provider, context => {
     let result: { id: string; name: string; details: TestDetails };
+    let testGuid: Guid;
 
     beforeEach(async () => {
-        const testGuid = Guid.create();
+        testGuid = Guid.create();
         context.fetchStub.resolves({
             ok: true,
             json: async () => ({
                 id: 'test-user-id',
                 name: 'Test User',
-                details: { 
-                    userId: testGuid.toString(), 
-                    role: 'admin' 
+                details: {
+                    userId: testGuid.toString(),
+                    role: 'admin'
                 }
             })
         } as Response);
@@ -39,4 +43,9 @@ describe('when refreshing with type safe details', given(an_identity_provider, c
     it('should deserialize details with proper types', () => {
         result.details.userId.should.be.instanceOf(Guid);
     });
+
+    it('should carry over the value the server sent', () => {
+        result.details.userId.toString().should.equal(testGuid.toString());
+        result.details.role.should.equal('admin');
+    });
 }));

package/identity/index.ts

@@ -5,3 +5,4 @@ export * from './IdentityProvider';
 export * from './IdentityProviderResult';
 export * from './IIdentityProvider';
 export * from './IIdentity';
+export * from './deserializeIdentityDetails';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/arc",
-    "version": "22.14.2",
+    "version": "22.15.0",
     "description": "TypeScript command, query, validation, identity, and messaging runtime for Cratis Arc — the CQRS application framework for ASP.NET Core — used by generated proxies.",
     "keywords": [
         "cratis",