@spotto/contract 1.0.69-alpha.24 → 1.0.69-alpha.26

package/dist/organisations/sso/types.d.ts

@@ -14,6 +14,34 @@ export declare type UnknownRoleAction<TRoleId = string> = {
     type: 'defaultRole';
     roleId: TRoleId;
 };
+/**
+ * One row in the org's role-mapping list. At sign-in the IdP-emitted claim
+ * (captured into `custom:g2g_role` via the per-org Cognito IdP
+ * `AttributeMapping`) is normalised to `string[]` and walked against this
+ * list in order; the first entry whose `propertyValue` appears in the
+ * normalised values assigns its `roleId`.
+ *
+ * Generic over the identifier type so the same shape covers both the wire
+ * layer (string IDs) and the Mongo storage layer (ObjectId).
+ */
+export interface RoleMapping<TId = string> {
+    _id: TId;
+    /**
+     * Value to look for in the IdP-emitted claim. Compared with `===` against
+     * each entry of the normalised `string[]` — case-sensitive, exact match.
+     */
+    propertyValue: string;
+    /** Spotto role to assign on match. */
+    roleId: TId;
+}
+/**
+ * Wire shape for creating / replacing mappings. `_id` is server-assigned on
+ * each write, so it's not part of the input.
+ */
+export interface RoleMappingInput {
+    propertyValue: string;
+    roleId: string;
+}
 export interface SsoEnabledBase<TRoleId = string> {
     enabled: true;
     /** Email domains owned by this org. One domain → one org (enforced at write time). */
@@ -26,6 +54,18 @@ export interface SsoEnabledBase<TRoleId = string> {
     inactivityTimeoutMinutes?: number;
     /** What to do when the role claim is missing or its value isn't a known Spotto role. */
     unknownRoleAction: UnknownRoleAction<TRoleId>;
+    /**
+     * IdP-side claim name that feeds the Cognito `custom:g2g_role` attribute.
+     * Pushed into the per-org Cognito IdP's `AttributeMapping` at onboard and
+     * any time it's updated. Examples: `g2g_role`, `roles`, `groups`, or a
+     * SAML AttributeName.
+     */
+    idpRoleClaim: string;
+    /**
+     * Org-scoped role-mapping list. Empty means every federated sign-in falls
+     * through to `unknownRoleAction`. See `RoleMapping`.
+     */
+    roleMappings: RoleMapping<TRoleId>[];
 }
 export interface SsoEnabledOidc<TRoleId = string> extends SsoEnabledBase<TRoleId> {
     mode: 'oidc';

package/dist/sso/get/response.d.ts

@@ -1,12 +1,22 @@
 import { SsoConfig } from '../../organisations/sso';
+import { SamlIdpSetup } from '../idp-setup';
 /**
- * Response shape for `GET /sso/orgs/:id`. Always returns a discriminated
- * `SsoConfig` — for orgs without SSO, the response is `{ enabled: false }`
- * rather than 404, so the FE can drive its UI from the discriminator
- * without separate "exists" handling.
+ * Response shape for `GET /sso/orgs/:id`.
+ *
+ * `config` is the persisted SSO config — always a discriminated `SsoConfig`,
+ * with `{ enabled: false }` for orgs that don't have SSO (rather than 404),
+ * so the FE can drive its UI from the discriminator without separate
+ * "exists" handling.
+ *
+ * `samlSetup` is populated only when `config.mode === 'saml'`. Carries the
+ * values the operator needs to paste into their IdP's SAML config dialog.
+ * Absent for OIDC and disabled orgs.
  *
  * Scoped to super-users only (via `sso:admin` + cross-account ancestry).
  * The customer-facing `GET /organisations/:id` deliberately does NOT
  * include this — SSO config is super-user-only data in the short term.
  */
-export declare type GetSsoOrgResponse = SsoConfig;
+export interface GetSsoOrgResponse {
+    config: SsoConfig;
+    samlSetup?: SamlIdpSetup;
+}

package/dist/sso/idp-setup.d.ts

@@ -0,0 +1,32 @@
+/**
+ * IdP-side configuration values an operator needs to plug into their IdP
+ * (e.g. Auth0's SAML2 Web App "Settings" JSON) to complete the SSO setup.
+ *
+ * Returned on the onboard and GET-org-SSO responses so the super-user UI
+ * can render copy-paste blocks. Generic-shaped — the FE renders them in
+ * the IdP-specific format the operator's tool expects (Auth0, Entra,
+ * Okta, etc., all take similar values in slightly different containers).
+ *
+ * The `acsUrl` (where the IdP POSTs the SAML response) is not in this
+ * payload because the FE already knows its Cognito hosted UI domain and
+ * can compose `${domain}/saml2/idpresponse` itself — keeps the backend
+ * free of an extra hosted-UI-domain config knob.
+ */
+export interface SamlIdpSetup {
+    /**
+     * The Cognito SP audience URN. For Auth0 SAML2 Web App, paste into the
+     * "audience" field. For Entra / Okta, the equivalent "Entity ID" /
+     * "Audience" field.
+     */
+    audience: string;
+    /**
+     * SAML attribute name mappings. Key is the Cognito-side user attribute
+     * name; value is the SAML attribute Name the IdP must emit. Auth0
+     * SAML2 Web App's "mappings" field takes this shape directly.
+     */
+    mappings: Record<string, string>;
+    /**
+     * NameID format Cognito expects from the IdP.
+     */
+    nameIdentifierFormat: string;
+}

package/dist/sso/idp-setup.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=idp-setup.js.map

package/dist/sso/idp-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idp-setup.js","sourceRoot":"","sources":["../../src/sso/idp-setup.ts"],"names":[],"mappings":""}

package/dist/sso/index.d.ts

@@ -1,5 +1,7 @@
 export * from './discover';
 export * from './get';
+export * from './idp-setup';
 export * from './onboard';
 export * from './offboard';
 export * from './revert';
+export * from './sso-mappings';

package/dist/sso/index.js

@@ -16,7 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./discover"), exports);
 __exportStar(require("./get"), exports);
+__exportStar(require("./idp-setup"), exports);
 __exportStar(require("./onboard"), exports);
 __exportStar(require("./offboard"), exports);
 __exportStar(require("./revert"), exports);
+__exportStar(require("./sso-mappings"), exports);
 //# sourceMappingURL=index.js.map

package/dist/sso/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sso/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA0B;AAC1B,wCAAqB;AACrB,4CAAyB;AACzB,6CAA0B;AAC1B,2CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sso/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA0B;AAC1B,wCAAqB;AACrB,8CAA2B;AAC3B,4CAAyB;AACzB,6CAA0B;AAC1B,2CAAwB;AACxB,iDAA8B"}

package/dist/sso/onboard/request.d.ts

@@ -1,3 +1,4 @@
+import { RoleMappingInput } from '../../organisations/sso';
 /**
  * Wire shape for `POST /sso/orgs/:id/onboard`. Operator-supplied fields only.
  *
@@ -7,9 +8,10 @@
  *   the org's `_id` (`buildSsoProviderName` → `sso-{orgId}`).
  * - `cognitoClientId` — orchestrator returns the Client ID it created.
  *
- * The IdP-side role claim name is also NOT a wire input: customers must
- * configure their IdP to emit a claim named `g2g_role`
- * (see `DEFAULT_IDP_ROLE_CLAIM`).
+ * `idpRoleClaim` IS a wire input — it names the IdP claim that the per-org
+ * Cognito `AttributeMapping` should wire into `custom:g2g_role`. Customers
+ * pick whatever their IdP naturally emits (e.g. `roles`, `groups`); Spotto
+ * maps the captured values to roles via `roleMappings`.
  */
 interface OnboardSsoOrgWireBase {
     emailDomains: string[];
@@ -22,6 +24,13 @@ interface OnboardSsoOrgWireBase {
     };
     callbackUrls: string[];
     logoutUrls: string[];
+    idpRoleClaim: string;
+    /**
+     * Initial mappings. Optional — when absent or empty, every federated
+     * sign-in falls through to `unknownRoleAction` until the admin populates
+     * mappings via `PUT /sso/orgs/:id/sso-mappings`.
+     */
+    roleMappings?: RoleMappingInput[];
 }
 export interface OnboardSsoOrgOidcRequest extends OnboardSsoOrgWireBase {
     mode: 'oidc';

package/dist/sso/onboard/request.js

@@ -1,16 +1,3 @@
 "use strict";
-/**
- * Wire shape for `POST /sso/orgs/:id/onboard`. Operator-supplied fields only.
- *
- * Two persisted-shape fields are NOT wire inputs:
- *
- * - `cognitoProviderName` — orchestrator computes it deterministically from
- *   the org's `_id` (`buildSsoProviderName` → `sso-{orgId}`).
- * - `cognitoClientId` — orchestrator returns the Client ID it created.
- *
- * The IdP-side role claim name is also NOT a wire input: customers must
- * configure their IdP to emit a claim named `g2g_role`
- * (see `DEFAULT_IDP_ROLE_CLAIM`).
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=request.js.map

package/dist/sso/onboard/request.js.map

@@ -1 +1 @@
-{"version":3,"file":"request.js","sourceRoot":"","sources":["../../../src/sso/onboard/request.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG"}
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../../src/sso/onboard/request.ts"],"names":[],"mappings":""}

package/dist/sso/onboard/response.d.ts

@@ -1,3 +1,4 @@
+import { SamlIdpSetup } from '../idp-setup';
 /**
  * Response shape for `POST /sso/orgs/:id/onboard`. Returned on the success
  * path; on failure the standard ValidationError / DatabaseError envelope
@@ -10,9 +11,15 @@
  *
  * `correlationId` threads through every audit log entry for this onboard
  * — useful to surface in the UI for ops to copy-paste when investigating.
+ *
+ * `samlSetup` is populated only on SAML onboards. It carries the values
+ * the operator needs to plug into their IdP's SAML config dialog (Auth0
+ * SAML2 Web App, Entra Enterprise Application, Okta SAML app, etc.).
+ * Absent for OIDC onboards.
  */
 export interface OnboardSsoOrgResponse {
     cognitoProviderName: string;
     cognitoClientId: string;
     correlationId: string;
+    samlSetup?: SamlIdpSetup;
 }

package/dist/sso/sso-mappings/index.d.ts

@@ -0,0 +1,2 @@
+export * from './request';
+export * from './response';

package/dist/sso/sso-mappings/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./request"), exports);
+__exportStar(require("./response"), exports);
+//# sourceMappingURL=index.js.map

package/dist/sso/sso-mappings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sso/sso-mappings/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAAyB;AACzB,6CAA0B"}

package/dist/sso/sso-mappings/request.d.ts

@@ -0,0 +1,14 @@
+import { RoleMappingInput } from '../../organisations/sso';
+/**
+ * Wire shape for `PUT /sso/orgs/:id/sso-mappings`.
+ *
+ * Atomic full-replace of the org's role-mapping configuration. Sends both
+ * `idpRoleClaim` (which IdP claim feeds `custom:g2g_role`) and the whole
+ * `roleMappings` array. The orchestrator validates roleIds, pushes any
+ * `idpRoleClaim` change to Cognito via `UpdateIdentityProvider`, then
+ * persists. Mapping `_id` values are server-assigned on each write.
+ */
+export interface UpdateSsoMappingsRequest {
+    idpRoleClaim: string;
+    roleMappings: RoleMappingInput[];
+}

package/dist/sso/sso-mappings/request.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=request.js.map

package/dist/sso/sso-mappings/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../../src/sso/sso-mappings/request.ts"],"names":[],"mappings":""}

package/dist/sso/sso-mappings/response.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Response shape for `PUT /sso/orgs/:id/sso-mappings`.
+ *
+ * Just a correlation id for stitching audit-log entries together. The FE
+ * re-fetches via `GET /sso/orgs/:id` to render the post-update state.
+ */
+export interface UpdateSsoMappingsResponse {
+    correlationId: string;
+}

package/dist/sso/sso-mappings/response.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=response.js.map

package/dist/sso/sso-mappings/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../../src/sso/sso-mappings/response.ts"],"names":[],"mappings":""}

package/dist/users/[id]/get/response.d.ts

@@ -18,5 +18,12 @@ export interface GetInternalUserResponse extends BaseGetUserResponse {
     type: 'INTERNAL';
     email: string;
     lastLogin?: number;
+    /**
+     * True while the user has an outstanding invite and has not yet set a
+     * password (no Cognito record). Cleared on `POST /users/invites/:token/accept`
+     * and absent for users created via the linking branch (existing Cognito
+     * record from another org membership).
+     */
+    invitePending?: boolean;
 }
 export declare type GetUserResponse = GetExternalUserResponse | GetInternalUserResponse;

package/dist/users/index.d.ts

@@ -3,3 +3,4 @@ export * from './current';
 export * from './post';
 export * from './get';
 export * from './[id]';
+export * from './invites';

package/dist/users/index.js

@@ -19,4 +19,5 @@ __exportStar(require("./current"), exports);
 __exportStar(require("./post"), exports);
 __exportStar(require("./get"), exports);
 __exportStar(require("./[id]"), exports);
+__exportStar(require("./invites"), exports);
 //# sourceMappingURL=index.js.map

package/dist/users/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/users/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA2B;AAC3B,4CAAyB;AACzB,yCAAsB;AACtB,wCAAqB;AACrB,yCAAsB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/users/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA2B;AAC3B,4CAAyB;AACzB,yCAAsB;AACtB,wCAAqB;AACrB,yCAAsB;AACtB,4CAAyB"}

package/dist/users/invites.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Response shape for `GET /users/invites/:token`. Returns minimal context
+ * so the FE can render "You've been invited to join <Org>" before the user
+ * sets their password. 404 is returned for not-found / expired / consumed
+ * (same response for all three to avoid enumeration).
+ */
+export interface GetInviteResponse {
+    email: string;
+    organisationName: string;
+}
+export interface AcceptInviteRequest {
+    password: string;
+}
+/**
+ * Response shape for `POST /users/invites/:token/accept`. Empty body — a
+ * 200 means the Cognito user has been created and the password is set;
+ * the FE can redirect to login.
+ */
+export declare type AcceptInviteResponse = Record<string, never>;

package/dist/users/invites.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=invites.js.map

package/dist/users/invites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invites.js","sourceRoot":"","sources":["../../src/users/invites.ts"],"names":[],"mappings":""}

package/dist/users/post/request.d.ts

@@ -10,6 +10,5 @@ export interface PostExternalUserRequest extends BasePostUserRequest {
 export interface PostInternalUserRequest extends BasePostUserRequest {
     type: 'INTERNAL';
     email: string;
-    password?: string;
 }
 export declare type PostUserRequest = PostExternalUserRequest | PostInternalUserRequest;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spotto/contract",
   "license": "ISC",
-  "version": "1.0.69-alpha.24",
+  "version": "1.0.69-alpha.26",
   "description": "Spotto's API Contract type definitions",
   "main": "./dist/index.js",
   "files": [
@@ -18,5 +18,5 @@
     "@types/geojson": "^7946.0.11",
     "shx": "^0.3.4"
   },
-  "gitHead": "892aa327162a98a8547b9e5142afabbe3a814ccd"
+  "gitHead": "c9d1c5e6716171c2910b310108a9a55d513fb4f2"
 }