@flowdular/sdk 0.2.4 → 0.3.0

package/modules/directory/spec/module.yaml

@@ -0,0 +1,351 @@
+schemaVersion: 2
+id: directory.core
+specVersion: 0.1.9
+status: approved
+name: Directory Core
+description: Lets an identity provider provision and deprovision workspace members and groups through SCIM 2.0, with a workspace-scoped bearer token, group to role mapping and deactivation that disables the membership without ever deleting the account.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+dependencies:
+  - id: system.core
+    range: ^0.7.0
+  - id: auth.core
+    range: ^0.13.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Persistence runs on the shared asynchronous database contract with explicit PostgreSQL SQL; every tenant table enables and forces row-level security with USING and WITH CHECK policies bound to the transaction-local tenant id, and the runtime role holds neither SUPERUSER nor BYPASSRLS.
+  - SCIM requests are served under /scim/v2 for one workspace and are authenticated only by a SCIM token of that workspace, a bearer credential separate from member API tokens, generated by the server, stored as a hash, shown in full once at creation and at rotation, revocable, and rate limited per token. Credentials that resolve to no token are budgeted on the caller, the workspace together with the remote address a trusted proxy reports, so a flood of invented credentials spends one window instead of one each. That budget is read only after a credential has failed to resolve, so a credential that does resolve is never refused by it; a caller a trusted proxy named answers 429 once it is spent, a caller no proxy names keeps its refusals answered because its window covers every caller of the workspace, and past the budget a refusal is answered without a log line so a flood cannot fill the log. The window map is bounded with expired windows dropped before windows still in use.
+  - Revocation of a SCIM token is terminal; the state table names no transition out of revoked, rotation of a revoked token is refused with a stable code, and a workspace that needs provisioning again creates a new token.
+  - A provisioned user is created through the passwordless entry point of the auth administration port, so no secret is drawn for it at all and none can be guessed or leaked. auth.core stores the unusable credential marker instead, so a password sign-in for the account is refused exactly as an unregistered address is, a self-service password change is refused with PASSWORD_NOT_SET, and the provisioning audit event records that the account holds no credential beside the SCIM token that created it. The account holds no password until the member sets the first one through the public password reset of auth.core, which stays open for it. Creating a user therefore never fails for a reason the provider did not cause.
+  - Refusals that reach a screen carry this module's own stable codes; an auth.core code this module does not name answers as one bounded refusal rather than as untranslated server text, and a fault of auth.core stays a fault.
+  - A SCIM token carries no member permission; every SCIM operation acts through the auth administration port as a service actor named by the token and is audited with the token id and the operation, never with the token value.
+  - Users are mapped to accounts and memberships through auth.core, and directory.core stores only the SCIM mapping (external id, user name, group membership, mapping identifiers, provisioning state) and never an account row, a password or a session.
+  - A user created through SCIM has no password and signs in through an enabled identity provider of the workspace; creating a user is refused with a stable SCIM error when the workspace has no enabled provider. A workspace that later enables none leaves the public password reset as the activation path for a member already provisioned, and refusing password sign-in for a provisioned member while a provider is enabled is a workspace policy this version does not offer (D-SCIM-RESET).
+  - Deprovisioning through active=false or DELETE on a user disables the membership in this workspace through the per-membership status and never deletes the account or touches other workspaces; a later active=true re-enables the membership.
+  - A SCIM group maps to exactly one workspace role through a mapping the owner configures; a user's role follows the highest-precedence mapped group among the groups the user belongs to, with the workspace default role when no mapped group applies, and an unmapped group changes nothing.
+  - Group membership changes are applied in the order received and are idempotent; a request that repeats the current state answers success and writes nothing.
+  - Filtering supports userName eq, externalId eq, displayName eq and id eq with a bounded page size; unsupported filters answer the SCIM error for an invalid filter, never a full listing.
+  - Every SCIM response uses the SCIM 2.0 error and list schemas with a stable scimType, and a request body is bounded by a ceiling derived from the largest group this service provider accepts, so a group write carrying its whole membership with member references is read rather than refused.
+  - The last active owner of a workspace cannot be deactivated or demoted through SCIM; the request is refused with a stable error and the owner acts through the administration screen.
+  - directory.core declares one data class to the platform registry while it composes, directory.core.provisioning-events, holding the provisioning log with a default retention of 365 days and an export. The sweep and the export run inside this module, keyset paged and bounded per call, in its own tenant-scoped transaction, and reach one workspace at a time. SCIM tokens and the user, group and membership mappings are configuration and the current directory picture, so they are declared as no swept class.
+permissions:
+  - id: directory.tokens.read
+    description: Read the SCIM tokens of the active workspace without their secrets.
+  - id: directory.tokens.manage
+    description: Create, rotate and revoke SCIM tokens and configure group to role mappings in the active workspace.
+  - id: directory.provisioning.read
+    description: Read the provisioning log and the SCIM user and group mappings of the active workspace.
+dataOwnership:
+  - directory.core owns SCIM tokens (hashed), SCIM user and group mappings, group to role mappings and the provisioning log.
+  - auth.core owns accounts, memberships, membership status and roles; directory.core acts on them only through the auth administration port.
+entities:
+  - id: scim-token
+    name: SCIM token
+    description: A workspace-scoped bearer credential an identity provider uses for provisioning.
+    fields:
+      - id: label
+        type: string
+        required: true
+        unique: tenant
+        maxLength: 120
+      - id: tokenFingerprint
+        type: string
+        required: true
+        maxLength: 32
+        description: Truncated SHA-256 of the token; the token itself is stored only as a hash.
+      - id: status
+        type: enum
+        required: true
+        values:
+          - active
+          - revoked
+      - id: lastUsedAt
+        type: datetime
+        required: false
+      - id: expiresAt
+        type: datetime
+        required: false
+    states:
+      field: status
+      values:
+        - active
+        - revoked
+      transitions:
+        - from: active
+          to: revoked
+          permission: directory.tokens.manage
+  - id: scim-user
+    name: SCIM user mapping
+    description: The link between a provider's SCIM user and a workspace membership.
+    fields:
+      - id: externalId
+        type: string
+        required: false
+        maxLength: 256
+      - id: userName
+        type: string
+        required: true
+        unique: tenant
+        maxLength: 320
+      - id: accountId
+        type: string
+        required: true
+        maxLength: 128
+      - id: active
+        type: boolean
+        required: true
+      - id: lastSyncedAt
+        type: datetime
+        required: true
+  - id: scim-group
+    name: SCIM group mapping
+    description: A provider group known to the workspace and, when mapped, the role it grants.
+    fields:
+      - id: externalId
+        type: string
+        required: false
+        maxLength: 256
+      - id: displayName
+        type: string
+        required: true
+        unique: tenant
+        maxLength: 200
+      - id: roleKey
+        type: string
+        required: false
+        maxLength: 64
+        description: The workspace role this group grants; empty means the group is tracked but grants nothing.
+      - id: precedence
+        type: integer
+        required: true
+        description: Lower wins when a user belongs to several mapped groups.
+      - id: memberCount
+        type: integer
+        required: true
+  - id: provisioning-event
+    name: Provisioning event
+    description: One SCIM operation as received and its outcome.
+    fields:
+      - id: token
+        type: reference
+        required: true
+        reference: scim-token
+      - id: operation
+        type: enum
+        required: true
+        values:
+          - user-create
+          - user-update
+          - user-deactivate
+          - user-reactivate
+          - group-create
+          - group-update
+          - group-delete
+          - membership-change
+      - id: subject
+        type: string
+        required: true
+        maxLength: 320
+        description: The SCIM resource id the operation targeted.
+      - id: outcome
+        type: enum
+        required: true
+        values:
+          - applied
+          - unchanged
+          - refused
+      - id: reason
+        type: string
+        required: false
+        maxLength: 64
+        description: A stable reason code on refusal.
+      - id: occurredAt
+        type: datetime
+        required: true
+screens:
+  - id: scim-tokens
+    kind: list
+    entity: scim-token
+    title: SCIM tokens
+    columns:
+      - label
+      - status
+      - tokenFingerprint
+      - lastUsedAt
+      - expiresAt
+    filters:
+      - status
+    navigationGroup: Administration
+  - id: group-mappings
+    kind: list
+    entity: scim-group
+    title: Group mappings
+    columns:
+      - displayName
+      - roleKey
+      - precedence
+      - memberCount
+    navigationGroup: Administration
+  - id: provisioning-log
+    kind: list
+    entity: provisioning-event
+    title: Provisioning log
+    columns:
+      - occurredAt
+      - operation
+      - subject
+      - outcome
+      - reason
+    filters:
+      - operation
+      - outcome
+    navigationGroup: Administration
+actions:
+  - id: create-token
+    entity: scim-token
+    permission: directory.tokens.manage
+    kind: create
+    risk: workspace-write
+    idempotent: false
+    description: Create an active token with a label and optional expiry; the token is returned once.
+  - id: rotate-token
+    entity: scim-token
+    permission: directory.tokens.manage
+    kind: custom
+    risk: workspace-write
+    idempotent: false
+    description: Replace the token value, keep the label and revoke the previous value; the new token is returned once.
+  - id: revoke-token
+    entity: scim-token
+    permission: directory.tokens.manage
+    kind: custom
+    risk: workspace-write
+    idempotent: true
+    description: Revoke the token; provisioning through it stops immediately.
+  - id: map-group
+    entity: scim-group
+    permission: directory.tokens.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Set or clear the role and precedence of a group; roles of affected members are recalculated.
+widgets: []
+settings:
+  - key: defaultRole
+    type: string
+    scope: tenant
+    default: member
+    description: The role a provisioned user receives when no mapped group applies; must be a role of the workspace.
+  - key: pageSizeMax
+    type: integer
+    scope: platform
+    default: 200
+    description: Upper bound of the SCIM count parameter; 1 to 1000.
+agentTools: []
+outOfScope:
+  - Passwords for provisioned users are not set; sign-in goes through an identity provider of the workspace, and an invitation e-mail is not sent.
+  - SCIM schemas beyond User, Group and the core enterprise extension attributes department and manager are not stored.
+  - Bulk operations and the ResourceTypes and Schemas discovery endpoints beyond the minimal required set are not offered in v1.
+  - Deleting an account or removing a membership through SCIM is not offered; an owner removes a member through the administration screen.
+  - A workspace policy that refuses password sign-in for a provisioned member while an identity provider is enabled is not offered; the public password reset of auth.core stays open for every account.
+decisions:
+  - id: D-SCIM-SCOPE
+    question: What does the first SCIM version cover?
+    answer: Users and Groups with group to role mapping, filters on userName, externalId, displayName and id, PATCH and PUT.
+    decidedBy: user
+  - id: D-SCIM-TOKEN
+    question: How does the identity provider authenticate?
+    answer: A workspace-scoped SCIM bearer token created by an owner, shown once, rotatable, revocable, rate limited and audited; not a member API token.
+    decidedBy: user
+  - id: D-SCIM-DEPROVISION
+    question: What does deprovisioning do?
+    answer: Both active=false and DELETE disable the membership in this workspace; the account and other memberships stay; removal is a manual owner action.
+    decidedBy: user
+  - id: D-SCIM-PASSWORD
+    question: Does a provisioned user get a password?
+    answer: No; the user signs in through an identity provider of the workspace, and creation is refused when none is enabled.
+    decidedBy: user
+  - id: D-SCIM-RESET
+    question: How does a provisioned member reach a workspace whose identity providers are all disabled?
+    answer: Through the public password reset of auth.core, which stays open for an account holding the unusable credential marker and sets its first password. Where a provider is enabled it remains the expected sign-in; a workspace policy refusing password sign-in for provisioned members is out of scope for this version.
+    decidedBy: default
+  - id: D-SCIM-ROLE-PRECEDENCE
+    question: Which role wins when a user is in several mapped groups?
+    answer: The mapped group with the lowest precedence number; the workspace default role when none applies.
+    decidedBy: default
+  - id: D-SCIM-LAST-OWNER
+    question: May SCIM deactivate or demote the last owner?
+    answer: No; refused with a stable error, the owner acts in the administration screen.
+    decidedBy: default
+  - id: D-SCIM-PERMISSIONS
+    question: Who manages SCIM?
+    answer: Owners hold directory.tokens.read, directory.tokens.manage and directory.provisioning.read; members hold none.
+    decidedBy: default
+  - id: D-SCIM-SCREENS
+    question: Which screens exist?
+    answer: SCIM tokens, group mappings and the provisioning log under Administration.
+    decidedBy: default
+acceptanceScenarios:
+  - id: DIRECTORY-DATA-CLASS-RETENTION
+    given: Two workspaces each hold four provisioning events on four consecutive days.
+    when: The platform sweeps directory.core.provisioning-events for the first workspace with a cutoff and a row limit, and then exports the class for it.
+    then: Only events strictly older than the cutoff are removed, never more than the limit, the second workspace keeps all four, and the export writes that workspace's events alone with the oldest and newest occurrence time; a workspace holding none exports zero rows and no range.
+  - id: DIRECTORY-TOKEN-CREATE
+    given: A principal holding directory.tokens.manage supplies a unique label.
+    when: The token is created, rotated and later revoked.
+    then: The token is returned once at creation and once at rotation, only its fingerprint is readable afterwards, a revoked token answers 401 on every SCIM request, and a member without the permission is refused before repository access.
+  - id: DIRECTORY-USER-CREATE
+    given: An active SCIM token and a workspace with an enabled identity provider.
+    when: The provider posts a SCIM User with userName and externalId.
+    then: An account without a password is created or reused only when it holds no other membership, an active membership with the default role is created through the auth administration port, the SCIM response carries the resource id, and a provisioning event records the operation with the token id and no token value.
+  - id: DIRECTORY-USER-NO-PROVIDER
+    given: An active SCIM token and a workspace with no enabled identity provider.
+    when: The provider posts a SCIM User.
+    then: The request is refused with a SCIM error of a stable scimType and nothing is written.
+  - id: DIRECTORY-USER-DEACTIVATE
+    given: A provisioned user with sessions in this workspace and a membership in another workspace.
+    when: The provider patches active to false, then sends DELETE, then patches active to true.
+    then: The first two disable this membership and revoke its sessions and tokens here while the other workspace keeps working, the account remains, and the third re-enables the membership.
+  - id: DIRECTORY-GROUP-ROLE
+    given: Two groups mapped to roles with different precedence and a provisioned user.
+    when: The provider adds the user to both groups, then removes the lower-precedence one, then removes the last.
+    then: The user's role becomes the lowest-precedence mapped role, then the remaining mapped role, then the workspace default role, each change audited, and a repeat of the same membership state writes nothing.
+  - id: DIRECTORY-LAST-OWNER
+    given: A workspace whose only active owner is a provisioned user.
+    when: The provider deactivates the user or removes them from the owner-mapped group.
+    then: The request is refused with a stable SCIM error and the owner keeps the role and the membership.
+  - id: DIRECTORY-FILTER
+    given: Provisioned users and groups.
+    when: The provider lists users with userName eq, lists groups with displayName eq, pages with startIndex and count above the platform maximum, and filters on an unsupported attribute.
+    then: The matching resources are returned in SCIM list responses, count is clamped to the platform maximum, and the unsupported filter answers the SCIM invalidFilter error.
+  - id: DIRECTORY-TOKEN-ROTATE-REVOKED
+    given: A workspace whose SCIM token was revoked.
+    when: An owner rotates that token.
+    then: The request is refused with the stable code TOKEN_REVOKED, the token stays revoked, no new value is minted, and SCIM requests presenting the old value still answer 401.
+  - id: DIRECTORY-SCIM-FLOOD
+    given: An active SCIM token of a workspace, a caller presenting invented credentials from an address a trusted proxy reports, and a caller presenting them where no proxy reports one.
+    when: Each presents many more credentials that resolve to no token than the refusal budget allows.
+    then: The first refusals answer 401, the named caller then answers 429 while the unidentified one keeps answering 401, and the workspace's own token is served afterwards in both cases, including from the flooded address itself.
+  - id: DIRECTORY-GROUP-BODY
+    given: An active SCIM token and a group of the workspace.
+    when: A provider replaces the group with the largest membership the service provider configuration advertises, each member carrying a reference.
+    then: The body is read and answered on its contents, and only a body past the derived ceiling is refused as too large.
+  - id: DIRECTORY-DENY
+    given: A request without a token, with a token of another workspace, or with a member API token.
+    when: Any SCIM endpoint is called.
+    then: The request answers 401 with the SCIM error schema, nothing is written, and the refusal is audited without the token value.
+  - id: DIRECTORY-SCREEN-PAGING
+    given: A workspace with more SCIM tokens and groups than one screen page holds.
+    when: An owner walks the SCIM tokens screen sorted by label with the status filter and the label search, and the group mappings screen sorted by precedence or displayName with the name search.
+    then: Each screen list answers keyset pages of at most 200 rows (50 by default) in the requested direction, consecutive pages neither overlap nor leave a gap, a full page carries an opaque cursor and a short page none, the cursor is signed and bound to the workspace, the sort and the filters so one cut under another answers CURSOR_INVALID, an unknown sort key, direction or filter value answers INVALID_INPUT, and the SCIM listing keeps its own startIndex and count paging (DIRECTORY-FILTER).
+  - id: DIRECTORY-TENANT-BOUNDARY
+    given: Two workspaces with SCIM tokens, mappings and provisioning events.
+    when: A runtime transaction bound to one workspace reads or writes any of them.
+    then: Only that workspace's rows are visible or mutable and a row carrying another tenant identifier is rejected by the forced policy.

package/modules/directory/src/acl/permissions.ts

@@ -0,0 +1,7 @@
+export const DIRECTORY_PERMISSIONS = {
+	read: 'directory.tokens.read',
+	manage: 'directory.tokens.manage',
+	provisioningRead: 'directory.provisioning.read',
+} as const;
+
+export const permissions = Object.freeze(Object.values(DIRECTORY_PERMISSIONS));