@oimlsmart/platform-server 0.1.0 → 0.1.2

package/migrations/0017_org_member_cones.sql

@@ -0,0 +1,28 @@
+-- Migration 0017 — the org-member DATA CONE (TODO.identity-features/09,
+-- wave A). Every org membership gains a nullable cone: the org
+-- administrator's answer to "what can this member see and do" —
+-- org-wide (the default; every existing membership keeps it SILENTLY,
+-- NULL reads as org-wide) / assigned (the member sees the org's rows
+-- only where NAMED — the operator on the test run, the assignment's
+-- performer, the engagement's inquirer) / read-only (the orthogonal
+-- modifier, composable: the member reads per the scope, the write gate
+-- refuses them). The canonical spellings: NULL | 'assigned' |
+-- 'read-only' | 'assigned+read-only' (the kernel's parseOrgMemberCone
+-- owns the grammar; a malformed cell fails CLOSED — the narrowest cone,
+-- never a silent re-widen).
+--
+-- EXPAND-ONLY, as every file in this set: a new nullable column, never
+-- a renumber, never a rewrite — wrangler keys the live registry's
+-- bookkeeping on the file name.
+--
+-- THE MONOREPO MIRROR: this file is authored HERE (this repo owns the
+-- live D1 since the wave-03 cutover); the byte-identical mirror in the
+-- smart monorepo's browser/server/db/migrations/ + the kernel's
+-- schema.sql end-state land as the coordinator's follow-up in the
+-- kernel-extraction wave (agent-585's re-home of packages/platform-
+-- server). Until then the kernel's defensive ensures (the
+-- migrateAuthTables / ensureMembershipSupport posture) grow the column
+-- on the platform's dev/test stores, and the byte-identity tripwire
+-- (src/__tests__/id-migrations-ssot.test.ts) carries this file as a
+-- dated, wave-referenced local-only allowance.
+ALTER TABLE org_memberships ADD COLUMN cone TEXT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimlsmart/platform-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The OIML SMART platform server kernel: the store seam (ServerStore + the D1 and SQLite implementations), the canonical D1 migration set both deployments apply, the instance profile, the mailer, the RBAC map, the OIDC/OAuth client cones, and the shared role/permission vocabulary. Consumed by the smart monorepo (browser/) and the identity service.",
   "type": "module",
   "repository": {

package/src/store/d1.ts

@@ -62,6 +62,7 @@ import {
   type InstrumentRegistrationScopeStatus,
   type PlatformEvent,
   resolveOrgContext,
+  parseOrgMemberCone,
   type RecoveryCodeState,
   type ServerStore,
   type SessionView,
@@ -258,6 +259,14 @@ export class D1ServerStore implements ServerStore {
         ).run()
         await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_org_memberships_org ON org_memberships (org_id, state)').run()
         await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_org_memberships_user ON org_memberships (user_id, state)').run()
+        // TODO.identity-features/09 (the org-member data cone): the cone
+        // column arrives with migration 0017 — a dev D1 predating it
+        // grows the column here. NULL = org-wide: existing memberships
+        // keep their posture silently.
+        const membershipCols = await this.db.prepare('PRAGMA table_info(org_memberships)').all<{ name: string }>()
+        if (!membershipCols.results.some(c => c.name === 'cone')) {
+          await this.db.prepare('ALTER TABLE org_memberships ADD COLUMN cone TEXT').run()
+        }
         const sessionCols = await this.db.prepare('PRAGMA table_info(sessions)').all<{ name: string }>()
         if (!sessionCols.results.some(c => c.name === 'active_org')) {
           await this.db.prepare('ALTER TABLE sessions ADD COLUMN active_org TEXT').run()
@@ -569,7 +578,9 @@ export class D1ServerStore implements ServerStore {
       // The stale stamp never lingers (the membership ended mid-session).
       await this.stmt('UPDATE sessions SET active_org = NULL WHERE user_id = ? AND active_org = ?', payload.id, activeOrg).run()
     }
-    return { ...payload, orgId: resolved.orgId, roles: resolved.roles }
+    // TODO.identity-features/09: the context membership's cone rides the
+    // payload — the entity gates enforce it without a store round-trip.
+    return { ...payload, orgId: resolved.orgId, roles: resolved.roles, cone: resolved.cone }
   }
 
   async deleteSession(token: string): Promise<void> {
@@ -1986,6 +1997,9 @@ export class D1ServerStore implements ServerStore {
       userId: row.user_id as string,
       orgId: row.org_id as string,
       roles,
+      // The cone (TODO.identity-features/09): NULL parses to the
+      // org-wide default — a pre-existing membership keeps its posture.
+      cone: parseOrgMemberCone((row.cone as string | null) ?? null),
       state: row.state as OrgMembershipState,
       isPrimary: row.is_primary === 1,
       invitedBy: (row.invited_by as string | null) ?? null,
@@ -2109,6 +2123,16 @@ export class D1ServerStore implements ServerStore {
     return this.getOrgMembership(userId, orgId)
   }
 
+  /** Set the membership's data cone (TODO.identity-features/09): the
+   *  canonical spelling, or NULL for the org-wide default. */
+  async setOrgMembershipCone(userId: string, orgId: string, cone: string | null): Promise<OrgMembership | null> {
+    await this.ensureMembershipSupport()
+    const existing = await this.getOrgMembership(userId, orgId)
+    if (!existing) return null
+    await this.stmt('UPDATE org_memberships SET cone = ? WHERE user_id = ? AND org_id = ?', cone, userId, orgId).run()
+    return this.getOrgMembership(userId, orgId)
+  }
+
   /** Remove the row (the declined invitation; the erasure's cleanup). */
   async deleteOrgMembership(userId: string, orgId: string): Promise<boolean> {
     await this.ensureMembershipSupport()

package/src/store/sqlite/schema.sql

@@ -522,6 +522,12 @@ CREATE TABLE IF NOT EXISTS org_memberships (
   activated_at TEXT,
   disabled_at TEXT,
   disabled_by TEXT,
+  -- TODO.identity-features/09 wave A — the org-member DATA CONE
+  -- (migration 0017): NULL (org-wide, the default) | 'assigned' |
+  -- 'read-only' | 'assigned+read-only'; the kernel's
+  -- parseOrgMemberCone owns the grammar; a malformed cell fails
+  -- CLOSED to the narrowest cone.
+  cone TEXT,
   UNIQUE (user_id, org_id)
 );
 CREATE INDEX IF NOT EXISTS idx_org_memberships_org ON org_memberships (org_id, state);

package/src/store/sqlite/store.ts

@@ -107,6 +107,14 @@ function migrateAuthTables(db: Database.Database): void {
            'active', 1, COALESCE(last_login, created_at)
     FROM users WHERE org_id IS NOT NULL
   `)
+  // TODO.identity-features/09 (the org-member data cone): the
+  // membership's cone column arrives with migration 0017 — a dev file
+  // predating it grows the column here. NULL = org-wide: existing
+  // memberships keep their posture silently.
+  const membershipCols = db.prepare('PRAGMA table_info(org_memberships)').all() as Array<{ name: string }>
+  if (membershipCols.length && !membershipCols.some(c => c.name === 'cone')) {
+    db.exec('ALTER TABLE org_memberships ADD COLUMN cone TEXT')
+  }
   // TODO.identity-sso/02+03 (the strong-authentication wave): the amr
   // provenance columns on sessions → codes → access tokens.
   if (!sessionCols.some(c => c.name === 'amr')) {
@@ -781,13 +789,16 @@ export function findPendingOrgJoinRequestByEmail(email: string): OrgJoinRequest
 // AS; the columns' last writer never resurrects a disabled membership.
 
 import type { OrgMembership, OrgMembershipState } from '../../store'
-import { resolveOrgContext } from '../../store'
+import { resolveOrgContext, parseOrgMemberCone } from '../../store'
 
 interface OrgMembershipRow {
   id: string
   user_id: string
   org_id: string
   roles: string
+  /** TODO.identity-features/09 — the membership's data cone (the nullable
+   *  column; absent on a pre-migration row read). */
+  cone?: string | null
   state: OrgMembershipState
   is_primary: number
   invited_by: string | null
@@ -803,6 +814,9 @@ function membershipPayload(row: OrgMembershipRow): OrgMembership {
     userId: row.user_id,
     orgId: row.org_id,
     roles: parseRoles(row.roles) ?? [],
+    // The cone (TODO.identity-features/09): NULL parses to the org-wide
+    // default — a pre-existing membership keeps its posture silently.
+    cone: parseOrgMemberCone(row.cone),
     state: row.state,
     isPrimary: row.is_primary === 1,
     invitedBy: row.invited_by,
@@ -844,7 +858,9 @@ function applySessionOrgContext(activeOrg: string | null, payload: AuthUserPaylo
   if (activeOrg && !(active && active.state === 'active')) {
     getDb().prepare('UPDATE sessions SET active_org = NULL WHERE user_id = ? AND active_org = ?').run(payload.id, activeOrg)
   }
-  return { ...payload, orgId: resolved.orgId, roles: resolved.roles }
+  // TODO.identity-features/09: the context membership's cone rides the
+  // payload — the entity gates enforce it without a store round-trip.
+  return { ...payload, orgId: resolved.orgId, roles: resolved.roles, cone: resolved.cone }
 }
 
 export function listOrgMemberships(userId: string): OrgMembership[] {
@@ -938,6 +954,17 @@ export function setOrgMembershipState(
   return getOrgMembership(userId, orgId)
 }
 
+/** Set the membership's data cone (TODO.identity-features/09): the
+ *  canonical column spelling, or NULL for the org-wide default. Answers
+ *  null when no membership exists. */
+export function setOrgMembershipCone(userId: string, orgId: string, cone: string | null): OrgMembership | null {
+  const db = getDb()
+  const existing = getOrgMembership(userId, orgId)
+  if (!existing) return null
+  db.prepare('UPDATE org_memberships SET cone = ? WHERE user_id = ? AND org_id = ?').run(cone, userId, orgId)
+  return getOrgMembership(userId, orgId)
+}
+
 /** Remove the row (the holder declining an invitation; the erasure's
  *  cleanup). The route refuses the PRIMARY membership. */
 export function deleteOrgMembership(userId: string, orgId: string): boolean {

package/src/store/sqlite.ts

@@ -67,6 +67,7 @@ import {
   setInstrumentRegistrationLifecycle,
   setOrgMembershipRoles,
   setOrgMembershipState,
+  setOrgMembershipCone,
   setOrgRegistryOrgState,
   setSessionActiveOrg,
   setUserActive,
@@ -412,6 +413,9 @@ export function createSqliteServerStore(): ServerStore {
     ): Promise<OrgMembership | null> {
       return setOrgMembershipState(userId, orgId, state, actor)
     },
+    async setOrgMembershipCone(userId: string, orgId: string, cone: string | null): Promise<OrgMembership | null> {
+      return setOrgMembershipCone(userId, orgId, cone)
+    },
     async deleteOrgMembership(userId: string, orgId: string): Promise<boolean> {
       return deleteOrgMembership(userId, orgId)
     },

package/src/store.ts

@@ -40,6 +40,15 @@ export interface AuthUserPayload {
    *  (absent = the primary role only). */
   roles?: string[]
   orgId: string | null
+  /** TODO.identity-features/09 — the ACTIVE org context's data cone (the
+   *  membership's posture, resolved by the session-backed read; the OP's
+   *  `cone` claim carries the same value). ABSENT on constructors that
+   *  never resolve a membership (the row-backed reads); NULL = the
+   *  context resolved no membership (an org-free account — the cone
+   *  never applies to it). The cone only ever NARROWS: the enforcement
+   *  reads it at the two choke points (the entity API's read/write
+   *  gates), never as a grant. */
+  cone?: OrgMemberCone | null
   avatarUrl?: string
   /** TODO.identity/04: the account's sign-in provider family ('demo',
    *  'github', 'oidc', the OP's account provider) — projected from the
@@ -670,6 +679,73 @@ export interface OrgJoinRequest {
  *  act, never an automatic one). */
 export type OrgMembershipState = 'invited' | 'active' | 'disabled'
 
+// ── the per-member data cone (TODO.identity-features/09) ─────────────
+// Every org membership carries a CONE — the org administrator's answer
+// to "what can this member see and do" (the design: the org-wide default
+// keeps today's behavior; 'assigned' narrows the member to the org's
+// rows that NAME them; 'read-only' is the orthogonal modifier that
+// refuses the member's writes). The cone lives on the membership row
+// (org_memberships.cone, a nullable TEXT column — NULL is org-wide, so
+// existing memberships keep their posture silently), rides the OP's
+// claims in the active-org context, and is enforced at the platform's
+// two choke points ONLY (the read gate and the write gate). THE
+// INVARIANT: the cone only ever NARROWS — nothing in this machinery can
+// grant.
+
+/** The cone's scope: org-wide (the default — every row the org sees) or
+ *  assigned (only the org's rows that NAME the member — the operator on
+ *  the test run, the assignment's performer, the engagement's inquirer). */
+export type OrgMemberConeScope = 'org-wide' | 'assigned'
+
+/** The parsed cone (the payload shape every consumer reads). */
+export interface OrgMemberCone {
+  scope: OrgMemberConeScope
+  /** The orthogonal modifier: the member reads per the scope but the
+   *  write gate refuses them (a reviewer's posture). */
+  readOnly: boolean
+}
+
+/** The DEFAULT cone (a NULL column): org-wide, writable — today's
+ *  behavior, kept silently by every pre-existing membership. */
+export const ORG_MEMBER_CONE_DEFAULT: OrgMemberCone = { scope: 'org-wide', readOnly: false }
+
+/** The FAIL-CLOSED cone: a stored value the parser cannot read narrows
+ *  to the tightest posture (never a silent re-widen — the platform's
+ *  standing doctrine: a malformed permission input never grants). */
+export const ORG_MEMBER_CONE_FAIL_CLOSED: OrgMemberCone = { scope: 'assigned', readOnly: true }
+
+/** The canonical column spellings (NULL is the default — the column
+ *  stays NULL for org-wide+writable, keeping the expand-only posture
+ *  clean). 'org-wide' parses but never encodes (it IS the default). */
+export function encodeOrgMemberCone(cone: OrgMemberCone): string | null {
+  if (cone.scope === 'assigned') return cone.readOnly ? 'assigned+read-only' : 'assigned'
+  return cone.readOnly ? 'read-only' : null
+}
+
+/** Parse the stored cone (total, never throws): NULL/empty/'org-wide'
+ *  answer the default; a recognized composition parses; ANYTHING else
+ *  fails CLOSED (the narrowest cone) — a hand-edited or corrupt row
+ *  narrows the member, it never widens them. */
+export function parseOrgMemberCone(raw: string | null | undefined): OrgMemberCone {
+  if (raw === null || raw === undefined) return { ...ORG_MEMBER_CONE_DEFAULT }
+  const tokens = raw.split('+').map(t => t.trim()).filter(Boolean)
+  if (tokens.length === 0) return { ...ORG_MEMBER_CONE_DEFAULT }
+  let scopeSeen: OrgMemberConeScope | null = null
+  let readOnly = false
+  for (const token of tokens) {
+    if (token === 'read-only') {
+      if (readOnly) return { ...ORG_MEMBER_CONE_FAIL_CLOSED } // a doubled modifier is not a spelling
+      readOnly = true
+    } else if (token === 'org-wide' || token === 'assigned') {
+      if (scopeSeen !== null) return { ...ORG_MEMBER_CONE_FAIL_CLOSED } // two scopes is not a spelling
+      scopeSeen = token
+    } else {
+      return { ...ORG_MEMBER_CONE_FAIL_CLOSED } // an unknown token
+    }
+  }
+  return { scope: scopeSeen ?? 'org-wide', readOnly }
+}
+
 /** An account's membership in ONE organization (the org_memberships
  *  row): the per-org role set + the lifecycle state. The PRIMARY
  *  membership (isPrimary) is the backward-compatible one: the users
@@ -684,6 +760,10 @@ export interface OrgMembership {
   /** The PER-ORG role set (JSON on the row): the roles the account holds
    *  when acting AS this org. */
   roles: string[]
+  /** The membership's data cone (TODO.identity-features/09), parsed from
+   *  the row's nullable column — the DEFAULT object when the column is
+   *  NULL (org-wide, writable); never null on the payload. */
+  cone: OrgMemberCone
   state: OrgMembershipState
   isPrimary: boolean
   invitedBy: string | null
@@ -693,13 +773,16 @@ export interface OrgMembership {
   disabledBy: string | null
 }
 
-/** The effective org context: the org the account acts AS and the role
- *  set that context carries. The session payloads and the OP's token
- *  claims both resolve through resolveOrgContext, so the two never
- *  drift. */
+/** The effective org context: the org the account acts AS, the role
+ *  set that context carries, and the context membership's data cone
+ *  (TODO.identity-features/09 — NULL when NO membership row resolved:
+ *  the pre-memberships dual-read and the org-free account carry no
+ *  cone). The session payloads and the OP's token claims both resolve
+ *  through resolveOrgContext, so the two never drift. */
 export interface OrgContextResolution {
   orgId: string | null
   roles: string[]
+  cone: OrgMemberCone | null
 }
 
 /**
@@ -733,14 +816,16 @@ export function resolveOrgContext(
     const m = context.active
     if (m && m.orgId === context.activeOrg && m.state === 'active') {
       const global = user.orgId ? [] : accountRoles
-      return { orgId: context.activeOrg, roles: [...new Set([...m.roles, ...global])] }
+      return { orgId: context.activeOrg, roles: [...new Set([...m.roles, ...global])], cone: m.cone }
     }
   }
-  if (!user.orgId) return { orgId: null, roles: accountRoles }
+  if (!user.orgId) return { orgId: null, roles: accountRoles, cone: null }
   const p = context.primary
-  if (!p) return { orgId: user.orgId, roles: accountRoles }
-  if (p.state !== 'active') return { orgId: null, roles: [] }
-  return { orgId: user.orgId, roles: [...new Set([...accountRoles, ...p.roles])] }
+  // The pre-memberships dual-read (no primary row) carries NO cone — the
+  // org-wide default the enforcement reads for a cone-less context.
+  if (!p) return { orgId: user.orgId, roles: accountRoles, cone: null }
+  if (p.state !== 'active') return { orgId: null, roles: [], cone: null }
+  return { orgId: user.orgId, roles: [...new Set([...accountRoles, ...p.roles])], cone: p.cone }
 }
 
 // ── the organization registry (TODO.identity-features/05) ────────────
@@ -1539,6 +1624,13 @@ export interface ServerStore {
     state: OrgMembershipState,
     actor?: string | null,
   ): Promise<OrgMembership | null>
+  /** Set the membership's data cone (TODO.identity-features/09): the
+   *  CANONICAL column spelling (encodeOrgMemberCone's answer — NULL is
+   *  the org-wide default) or NULL to clear. The input's validation is
+   *  the ROUTE's (parse + re-encode; the store writes what it is given,
+   *  the parser's fail-closed posture backstops a bad cell). Answers
+   *  null when no membership exists. */
+  setOrgMembershipCone(userId: string, orgId: string, cone: string | null): Promise<OrgMembership | null>
   /** Remove the row — the holder declining an invitation, and the
    *  erasure's cleanup. (The routes refuse the PRIMARY membership: the
    *  primary binding moves through the account's role/org assignment,