HiveCast Platform

Appearance

Organizations ​

Status: target state. Organizations exist in the schema as ownerType: 'organization' on Space records, but no membership management, no org creation, no admin UI, no JIT provisioning, no SSO, no role-based access is implemented today. This page documents the design so the schema and the loose-ends are coherent.

What an organization is (target) ​

Per ARCHITECTURE-PLATFORM-TOPOLOGY.md §2 and §3, an organization is a multi-principal owner of one or more Spaces. The platform topology calls out three deployment scenarios that motivate this:

  • Personal accounts (today): one principal, one or more Spaces, owner type principal.
  • Organizations (target): many principals, shared Spaces, owner type organization, role-based membership.
  • Enterprises (target): an organization with its own Matrix daemon, corporate SSO (Okta/Entra/Duo), JIT membership provisioning.

The example in ARCHITECTURE-PLATFORM-TOPOLOGY.md §2 is "Acme Corp Daemon" with root: COM.ACME-CORP, departments under that (COM.ACME-CORP.ENG.*, COM.ACME-CORP.SALES.*), and public exports under COM.ACME-CORP.PUBLIC.*.

What is in code today ​

Source: projects/matrix-3/packages/system-auth/src/host-auth.ts:55:

ts
export type HostSpaceOwnerType = 'principal' | 'organization' | 'system' | 'service';

That is the entire implementation. 'organization' is a permitted value on IHostSpaceRecord.ownerType, but no creation flow, membership store, role assignment, or admin op references the value. A Space stamped with ownerType: 'organization' today has no organization to point at — ownerPrincipalId would have to refer to a principal.

There is no IHostOrganizationRecord type. There is no auth.organization.* op family. There is no membership index.

What an organization needs (design) ​

A complete organization implementation needs:

  • An organization record: { id, displayName, contactEmail, ownerPrincipalId, status, createdAt, updatedAt }.
  • A membership store: { organizationId, principalId, role, joinedAt, status } with roles like owner, admin, member.
  • Org-scoped authority roots: COM.ACME-CORP instead of per-principal COM.NIMBLETEC.RICHARD-SANTOMAURO.
  • Org-aware Space creation: auth.space.create accepting ownerType: 'organization', ownerOrganizationId.
  • Membership ops: org.invite, org.accept, org.remove, org.list-members.
  • Org-aware authorization: every op that today checks principalId === resource.ownerPrincipalId would need to check membership too.
  • Admin UI: a per-org dashboard, member management, billing scope.

None of that is in code. Adding it without a clear scope-creep guard would touch every op in system-auth.

Workaround today ​

Until orgs land, multi-user Spaces are emulated by sharing principal credentials, which is wrong and unsafe. The pragmatic workaround for small teams is:

  • One principal per user. Users sign in as themselves.
  • Each user creates their own Space.
  • Users publish actors via system.registry, allowing other principals to invoke published mounts.

This is the federation model — see Reference: Actor surfaces. It does not provide shared ownership; it provides discoverable per-principal services. For shared ownership, wait for the org work.

Enterprise SSO (further target) ​

workspaceRealm and the home-realm-discovery design in ARCHITECTURE-PLATFORM-TOPOLOGY.md §3 anticipate enterprise SSO:

1. User enters email: jane@acme.com
2. System detects acme.com is a claimed domain
3. Redirects to Acme's OIDC IdP (Okta/Entra/Duo)
4. User authenticates + MFA
5. JIT membership provisioning in Acme org
6. NATS user creds scoped to COM.ACME-CORP department subjects

The schema can carry the data (workspaceRealm, addressRoots[].root); the redirect to enterprise IdP and JIT provisioning code does not exist.

Loose ends ​

There is no current loose-end item dedicated to org implementation. The closest related items:

  • WORKSTREAMS/product-launch/CONSTRAINTS.md C8 — per-principal account isolation.
  • ARCHITECTURE-PLATFORM-TOPOLOGY.md §6 — Multi-User Isolation.
  • WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md — authority-root model that orgs would extend.

When org work is scheduled, an explicit WORKSTREAMS/organizations/ directory should own the spec.

Why not in the launch path ​

Per WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md and the launch-readiness ledger, the launch model is single-principal Devices. Multi-principal organizations add complexity orthogonal to the launch story (one user installs Matrix; one user pairs Devices; one user sees their fleet). Organizations are explicitly post-launch.

See also ​

  • Users — the principal model orgs would extend.
  • Spaces — ownerType enumeration.
  • Ownership — what changes when orgs land.

Source: projects/matrix-3/packages/system-auth/src/host-auth.ts:55-69 (the HostSpaceOwnerType enum is the entire current org-related implementation). ARCHITECTURE/ARCHITECTURE-PLATFORM-TOPOLOGY.md §2-3 for the design intent.