@wildo-ai/saas-technical-doc 1.1.4 → 1.1.5

package/dist/esm/content/application-consumer-documentation-content.techdoc.js

@@ -20,9 +20,12 @@
  * fact in it is projected from sources the application already accepted — its own resource
  * registry, its declared API-reference categories, and each specification's purpose and lifecycle.
  *
- * What remains genuinely deferred is a page PER resource. Those need a variable unit set, and the
- * renderer's route table is deliberately fixed (see `pathForUnit`), so an application-owned unit
- * still fails closed rather than acquiring an implicit route.
+ * A page PER resource followed, as a generated tier with its own reserved namespace (see
+ * `pathForUnit`). And a cross-resource BUSINESS use case — the journey this module can never write,
+ * because it belongs to one application — is authored by that application as a documentation
+ * chapter its plan declares (#874, `application-documentation-chapters.ts`), again in a reserved
+ * namespace. A unit whose ref an application chose freely still fails closed rather than acquiring
+ * an implicit route.
  */
 export const APPLICATION_CONSUMER_DOCUMENTATION_AUTHORED_CONTENT_V1 = [
     {
@@ -737,11 +740,6 @@ administration surface permits that sequence. Do not mark it as default yet.
 
 {{CONSUMER_FACT:source:consumer-fact:access-single-sign-on#connectionConfigurationMarkdown}}
 
-> **Current limitation:** keep \`bypassAppMFA\` off. The configuration field is
-> present, but the current authentication runtime does not use it to decide
-> whether the application requests another factor. Prove the actual sign-in
-> journey with a controlled account; do not use this field as audit evidence.
-
 > **SSO role mapping is an access grant.** Test every mapped value, keep the
 > fallback role non-administrative, and verify an expected refusal. A provider
 > group name should never become broad application authority merely because it
@@ -974,7 +972,7 @@ that can reveal a mapping defect:
 | Newly eligible person, when first-sign-in creation is enabled | The intended user and membership lifecycle occurs with the fallback role |
 | Person with a mapped provider role or group | The exact external value maps to the intended application role |
 | Person outside an allowed domain or mapping | The connection refuses the identity without revealing another account |
-| Person with application MFA requirements | The actual post-provider journey is observed; do not infer it from the currently non-operative \`bypassAppMFA\` field |
+| Person with application MFA requirements | The actual post-provider journey is observed. A connection cannot exempt anyone from the application's requirement: the declared policy is enforced on the federated lane too, and an organization may only tighten it |
 | Independent recovery administrator | Provider outage or mapping failure does not remove all administrative access |
 
 Use controlled test identities and non-sensitive application actions. Do not
@@ -3494,9 +3492,10 @@ credentials and unnecessary personal data.`,
 
 SCIM lets an identity directory maintain a defined population of users and
 organization memberships. Choose it when your directory should own repeatable
-joiner, mover and leaver changes. The application supports **SCIM Users**, not
-SCIM Groups; a directory \`department\` can be mapped to one existing
-organization unit.
+joiner, mover and leaver changes. The application supports **SCIM Users** and
+**SCIM Groups**. A directory \`department\` can be mapped to one existing
+organization unit, and a directory group can become an organization unit of its
+own — see *Provision organization units from your directory*.
 
 > **SCIM provisions access; it does not sign people in.** Configure and prove
 > single sign-on separately. A directory-managed person needs both a correctly
@@ -3588,8 +3587,8 @@ same membership or unit assignment.`,
 
 Use this page to decide whether a directory or provisioning bridge is compatible
 with this application **before** configuring production users. The application
-implements a focused SCIM 2.0 User service. It is not a generic LDAP endpoint and
-it does not implement SCIM Groups.
+implements a focused SCIM 2.0 User and Group service. It is not a generic LDAP
+endpoint, and its Group resource maps to organization units rather than to roles.
 
 ## Supported profile at a glance
 
@@ -3597,12 +3596,12 @@ it does not implement SCIM Groups.
 | --- | --- | --- |
 | Protocol | SCIM 2.0 over HTTPS with \`application/scim+json\` | SCIM 1.1 and direct LDAP binds are not accepted |
 | Authentication | A dedicated organization SCIM bearer token | The token selects one organization; it is not a user session or ordinary API key |
-| Resources | \`Users\` plus SCIM discovery documents | \`Groups\` is not implemented; group assignment can scope which users the provider sends but must not call \`/Groups\` |
-| User operations | Create, list, read, full replace, partial update and deactivate; Bulk accepts up to 100 operations | Organization-unit reconciliation differs by operation, as shown below |
+| Resources | \`Users\`, \`Groups\` and SCIM discovery documents | A \`Group\` is an organization unit, not a role. It is available only once an administrator sets the unit role on the SCIM provisioning configuration; until then every \`/Groups\` request answers 403 |
+| User operations | Create, list, read, full replace, partial update and deactivate; Bulk accepts up to 100 User or Group operations | Organization-unit reconciliation differs by operation, as shown below |
 | Filtering | User lookup filters with a published maximum result size of 200 | Test the provider’s exact matching query before broad rollout |
 | Password changes | Not supported | Use the configured human sign-in or SSO journey; do not synchronize directory passwords |
 | Sorting and ETags | Not supported | A provider must not require sorting or conditional ETag writes |
-| Request budget | 300 requests per minute for each SCIM token | A 429 response includes retry information; reduce concurrency rather than rotating addresses |
+| Request budget | 6,000 requests per minute for each SCIM token, sized for the request bursts Microsoft Entra ID and Okta send (neither uses Bulk) | A 429 response carries an integer \`Retry-After\`; follow it rather than rotating addresses |
 
 The public discovery documents are available beneath the SCIM base URL:
 
@@ -3648,7 +3647,7 @@ and does not prove that the person can complete SSO.
 | Provider requirement | Compatible expectation |
 | --- | --- |
 | Discovery | The provider can read \`ServiceProviderConfig\`, \`Schemas\` and \`ResourceTypes\` and respect the advertised feature set |
-| Resource types | User provisioning works without calling \`/Groups\` |
+| Resource types | \`/ResourceTypes\` lists both \`User\` and \`Group\`. User provisioning works whether or not the provider calls \`/Groups\` |
 | Update behavior | The provider can operate with the documented PUT/PATCH consequences, especially when department controls unit access |
 | Authentication | The provider can send the dedicated bearer token in the HTTPS \`Authorization\` header |
 | Matching and pagination | Its exact user filter and result-window behavior work within the published limit |
@@ -3711,9 +3710,9 @@ matched exactly, after trimming, against the organization-unit mapping.
 | --- | --- | --- |
 | \`POST /Users\` | Creates or links the person according to the lifecycle configuration | Reconciles an exact mapped department when unit mapping and a default unit role are configured |
 | \`PUT /Users/{id}\` | Replaces the maintained profile and active state | Performs authoritative unit reconciliation from the full department value |
-| \`PATCH /Users/{id}\` | Applies supported partial profile or active-state changes | **Does not currently reconcile organization units** |
+| \`PATCH /Users/{id}\` | Applies supported partial profile or active-state changes | Reconciles units only when the PATCH sets or removes the department; a PATCH that does not touch the department leaves unit assignments unchanged |
 | \`DELETE /Users/{id}\` | Runs the configured deactivation behavior; it does not physically erase the person | Does not perform a department-to-unit reconciliation |
-| \`POST /Bulk\` | Executes supported user operations individually | **Does not currently reconcile organization units**, including Bulk PUT operations |
+| \`POST /Bulk\` | Executes each User or Group operation individually, exactly as the same request would on its own | The same effect as the individual operation: a Bulk PUT reconciles like \`PUT\`, a Bulk PATCH like \`PATCH\`. A \`bulkId:\` reference to a resource created earlier in the same request is replaced by its id, so one request can create a user and add them to a new group |
 
 This difference matters with providers that normally send PATCH. Do not enable
 authoritative department-to-unit mapping merely because user creation worked.
@@ -3858,18 +3857,24 @@ plaintext secret is returned once; store it immediately in the identity
 provider’s secret store. Keep it out of source control, screenshots, logs,
 tickets and reusable examples.
 
-The current request budget is **300 requests per minute per token**. When the
-service returns a rate limit, follow its retry information and reduce
-concurrency instead of starting parallel retries.
+The current request budget is **6,000 requests per minute per token**. It is
+sized for how identity providers really push: neither Microsoft Entra ID nor
+Okta uses SCIM Bulk, so a first sync arrives as a burst of individual requests.
+When the service returns a rate limit, it states an integer \`Retry-After\` in
+seconds; follow it instead of starting parallel retries.
 
 ## Treat deactivation as a high-impact choice
 
-The current deactivation path marks both the global user and the addressed
-organization membership inactive. For a person who belongs to several
-organizations, this can affect more than the directory-owned membership. Test
-that case before production rollout. A later \`active:true\` does not prove that
-the organization membership was restored; verify both layers before announcing
-recovery.`,
+Deactivation withdraws the person's membership in **this organization only**,
+together with the access that membership conferred. Their account and their
+memberships in other organizations are not touched: one organization's
+directory cannot lock a person out of another.
+
+A later \`active:true\` restores the membership with the organization's
+**current default role**, not the roles the person held before. Re-grant any
+additional role deliberately. A person whose account was disabled by the
+application operator is not re-enabled by the directory; restoring them is the
+operator's decision.`,
     },
     {
         managedPath: 'user-administration/scim-microsoft-entra.md',
@@ -3944,18 +3949,36 @@ Keep the first mapping small and observable:
 | Account-enabled expression | \`active\` | Test disable and re-enable as separate access events |
 | \`department\` | Enterprise User \`department\` | Enable only if department is an access-control authority |
 
-This application currently exposes **Users**, not SCIM **Groups**. Disable group
-object provisioning and Push Groups-style expectations. Entra groups may still
-be useful on the Entra side to decide who is assigned to the enterprise
-application, but they are not imported as application groups.
+This application exposes **Users** and **Groups**. A pushed Entra group becomes
+an organization UNIT, and its members become assignments in that unit carrying
+the unit role configured on the SCIM provisioning configuration — it does not
+become a role or a permission set. Enable group provisioning only if you intend
+your directory's groups to define unit access; leave it off and Entra groups
+remain purely an Entra-side way to decide who is assigned to the enterprise
+application.
+
+Two consequences to plan for. A group this application did not create is never
+adopted, so an Entra group whose name matches a unit an administrator authored
+creates a second unit rather than taking over the first. And a group Entra
+deletes takes its unit, and every assignment in it, with it.
+
+While the directory is connected, a unit it created is **managed by the
+directory**: its name and its members are refused if changed in this
+application, because the next push would put them back. The organization-units
+screen marks such a unit with its source (SCIM) and the directory's own group
+identifier. Rename the group, or change who is in it, in Entra. An assignment's
+unit role, and the unit's code, type, status and position, are not
+directory-managed and stay editable here. If the directory is disconnected —
+every SCIM token revoked — the unit becomes editable like any other.
 
 ## Treat department-to-unit mapping as a controlled rollout
 
-The application reconciles organization units on direct \`POST /Users\` and full
-\`PUT /Users/{id}\` operations. It does **not** currently reconcile units on
-\`PATCH\` or \`Bulk\`. Entra can use PATCH for attribute changes, so a successful
-profile update does not prove that moving a person between departments removed
-their former unit access.
+The application reconciles organization units on \`POST /Users\`, on full
+\`PUT /Users/{id}\`, and on a \`PATCH\` that sets or removes the department — and
+on the same operations inside \`Bulk\`. A PATCH that does not touch the department
+leaves unit assignments unchanged. Entra sends PATCH for attribute changes, so
+confirm that a department move actually reaches the application as a department
+change before relying on it to remove former unit access.
 
 Before making department authoritative:
 
@@ -4030,10 +4053,20 @@ another Okta application whose provisioning connector lets you supply a SCIM
 base URL and bearer token. If the application later has a reviewed Okta
 Integration Network entry, follow that entry instead of duplicating it.
 
-The application accepts SCIM **User** resources. It does not currently expose a
-SCIM Group resource, so do not enable Push Groups or depend on group-object
-imports. An Okta group can still control which users are assigned to the Okta
-application.
+The application accepts SCIM **User** and **Group** resources. A pushed group
+becomes an organization UNIT rather than a role: its members receive the unit
+role configured on the SCIM provisioning configuration, which confines which
+records they reach and never widens their permissions. Enable Push Groups only
+if that is what you intend; otherwise an Okta group can still control which users
+are assigned to the Okta application without being pushed.
+
+Note that Okta creates a group without an \`externalId\`, which this application
+handles: the group is identified by the id returned when it was created.
+
+A pushed group's name and members are managed by Okta while it stays connected:
+changing either in this application is refused, because the next push would
+restore it. Make those changes in Okta; unit roles and the unit's other settings
+stay editable here.
 
 ## Connect Okta
 
@@ -4068,10 +4101,11 @@ Map Okta’s department to the SCIM Enterprise User extension only when it is
 authoritative enough to change access. Then map exact department values to
 existing application organization units.
 
-> **Operation limitation:** organization-unit reconciliation currently runs for
-> direct user creation and full replacement. It does not run for PATCH or Bulk.
-> Capture the operation Okta sends for a department change and prove that the
-> old unit assignment is removed before production rollout.
+> **Operation boundary:** organization-unit reconciliation runs on user creation,
+> full replacement, and a PATCH that sets or removes the department, including the
+> same operations inside Bulk. A PATCH that does not touch the department leaves
+> unit assignments unchanged. Capture the operation Okta sends for a department
+> change and prove that the old unit assignment is removed before production rollout.
 
 ## Prove one complete lifecycle
 
@@ -4152,7 +4186,7 @@ compliant SCIM User. A common starting point is:
 | \`sn\` | \`name.familyName\` | Empty-value behavior |
 | \`displayName\` | \`displayName\` | Which system owns later edits |
 | \`department\` | Enterprise User \`department\` | Whether it is authoritative for unit access |
-| Disabled-account state | \`active:false\` | Global user and membership deactivation consequence |
+| Disabled-account state | \`active:false\` | Withdraws the membership in this organization only; the account and other memberships stay |
 
 These are mapping decisions, not guaranteed attributes in every LDAP schema.
 Inspect representative entries and document the source object classes,
@@ -4198,8 +4232,10 @@ A production bridge needs all of the following:
 - a tested response to rate limiting, token rotation and partial batch failure.
 
 Do not use Bulk for a first implementation merely for speed. The application
-supports a bounded Bulk request, but Bulk currently does not perform
-organization-unit reconciliation. Start with observable individual operations.
+supports a bounded Bulk request whose operations behave exactly as the same
+individual requests, but a Bulk response reports each operation's status
+separately, which makes failures harder to observe. Start with observable
+individual operations.
 
 ## Validate before production
 
@@ -4304,8 +4340,9 @@ flowchart LR
 Reconciliation becomes active only with at least one explicit mapping and a
 default unit role. On supported direct user creation and full replacement, the
 directory becomes authoritative: a changed, blank or unmapped department can
-remove former assignments, including manual ones. **PATCH and Bulk do not
-currently perform this reconciliation.** Prove the exact operation used by
+remove former assignments, including manual ones. A PATCH performs this
+reconciliation only when it sets or removes the department; Bulk operations
+behave as the same individual requests. Prove the exact operation used by
 your identity provider.`,
     },
     {
@@ -4345,8 +4382,9 @@ unit assignment and sign-in behavior after every change.
    unit assignment was removed.
 6. **Send blank, unmapped and wrong-case departments.** Verify the exact result
    before making mapping authoritative.
-7. **Deactivate a multi-organization person.** Inspect both the global user and
-   every affected membership.
+7. **Deactivate a multi-organization person.** Confirm that only this
+   organization's membership became inactive and their other memberships
+   are unchanged.
 8. **Recover the person.** Confirm that the user and intended membership are
    both **Active** and that enterprise sign-in succeeds.
 
@@ -4417,7 +4455,7 @@ change completed successfully.
 | **409** | An existing identity or membership conflicts; inspect it instead of creating a duplicate |
 | **429** | Follow retry information and reduce concurrency |
 | Profile value is missing | Test the exact mapping expression against the real directory payload |
-| Unit did not change | Confirm exact department value and case, explicit mapping, existing unit, default role and a supported direct create/full replacement operation |
+| Unit did not change | Confirm exact department value and case, explicit mapping, existing unit, default role, and that the operation carried the department (create, full replacement, or a PATCH that sets it) |
 | Person remains unable to sign in | Check enterprise sign-in, global user state and organization membership state separately |
 
 ## Recover safely
@@ -4956,13 +4994,83 @@ application path you operate.
 
 {{CONSUMER_FACT:source:consumer-fact:organization-siem-export#deliveryValuesMarkdown}}
 
-The current worker posts **one event per HTTP request**. Do not configure a
-receiver, load balancer or billing estimate on the assumption that \`batchSize\`
-or \`batchWindowSeconds\` reduces request volume. The
-\`includeRawEventData\` and \`includeDeviceContext\` flags are also reserved in
-the current runtime: changing them does not remove those fields from the emitted
-envelope. Treat data minimization at the receiver as necessary until those
-configuration controls are implemented end to end.
+The current worker posts **one event per HTTP request**, and there is no setting
+that changes that — size a receiver, load balancer or billing estimate on one
+request per event.
+
+Two configuration fields used to sit here promising otherwise — \`batchSize\` and
+\`batchWindowSeconds\` — each accepted, stored and read by nothing. They were
+removed rather than documented as reserved: a stored number that does not change
+behaviour is worse than its absence, because a receiver sized on it is sized wrong.
+
+## Limit what an exported event carries
+
+\`exportProjection\` decides what this destination receives. It is the only place
+an export can be narrowed **before** the data leaves; everything else — a filter,
+a severity minimum — decides *whether* an event is sent, not *what* it contains.
+
+Set it per destination, not per application: two receivers under two different
+agreements are two different answers.
+
+| Declaration | Admits |
+| --- | --- |
+| \`disclosedTiers: ["attribution"]\` | the user's email address, IP address, user agent, geolocation and client-install identifier |
+| \`disclosedTiers: ["context"]\` | correlation identifier, originating frontend, organization and application names, authentication method and source |
+| \`disclosedTiers: ["detail"]\` | the per-event \`eventData\` object **and the outcome reason**, subject to the next row |
+| \`disclosedEventDataClasses: ["administrative"]\` | only the \`eventData\` of events describing configuration or system state |
+| \`disclosedEventDataClasses: ["subject-detail"]\` | also the \`eventData\` of events describing a person |
+
+**Declaring \`detail\` while withholding \`attribution\` is the mistake to avoid.**
+An authentication event's \`eventData\` carries the email address and IP address
+that withholding attribution was meant to keep back, so the narrowing reads as a
+control while changing nothing that matters. Pair it with
+\`disclosedEventDataClasses: ["administrative"]\`.
+
+The outcome reason sits in \`detail\` rather than \`context\` for the same reason,
+and it is worth understanding before you rely on either tier. It is not a field of
+its own: the application lifts it out of the event's own \`eventData\`. Most of the
+time it is a short, impersonal failure reason — but **19 event types carry a
+reason somebody typed**, including organization lifecycle changes, emergency
+access, forced password resets and retained-data access, where it is the
+operator's own words and may name anyone. Withholding an event's detail therefore
+withholds its reason too.
+
+A **floor always survives** whatever you declare: event identifier, event type,
+category, severity, timestamp, organization, the acting user's identifier, source
+service, source version, source environment, and outcome. Two reasons, and only
+the first is about privacy. The event identifier is what your receiver
+de-duplicates on, and deliveries are retried — an export minimized past it
+produces duplicates in your SIEM rather than fewer records. The event type,
+severity and source version are header fields of the CEF and LEEF grammars, which
+are positional: omitting one does not shorten the record, it corrupts every field
+after it. The acting user's identifier is an opaque reference, never a name or an
+address, so it lets you correlate one actor's activity without receiving their
+identity — which is usually the trade a minimized export exists to make.
+
+One capability cost to know about, because nothing warns you at the time:
+withholding \`detail\` makes OCSF exports coarser. The application refines an
+API-activity event's \`activity_id\` by reading the verb out of \`eventData\`, so
+with the object withheld a create and a delete both report the generic
+\`Other\` activity and share a \`type_uid\`. The event type is still carried in
+\`activity_name\` and \`metadata.event_code\`, so nothing is wrong — but a
+detection rule or dashboard that groups by \`type_uid\` will stop separating them.
+CEF, LEEF and structured JSON are unaffected.
+
+Withheld fields are **absent**, not empty. No blank CEF custom-string slot, no
+null JSON key, no empty OCSF attribute — so a receiver's "field is present but
+empty" rule will not fire, and a rule keyed on a withheld field simply never
+matches. The same projection applies to every wire format, because it is applied
+once, before the event is signed and queued, rather than per format.
+
+Omit the whole block and the destination receives the full envelope. That is the
+behaviour of every destination configured before this control existed, so
+introducing it changes nothing until you declare a narrowing.
+
+Verify a narrowing the way you verify a filter: perform one controlled event,
+read the received copy, and confirm both that the withheld fields are absent and
+that the event identifier still matches the source audit record. Minimization
+does not alter the source audit trail — the full record remains in the
+application, and a narrowed feed is not evidence that less was recorded.
 
 ## Filter for purpose and volume