@owlmeans/server-auth-identity 0.1.18-rc.2 → 0.1.18-rc.21

package/src/resolver.ts

@@ -0,0 +1,165 @@
+import { appendContextual } from '@owlmeans/context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { Criteria } from '@owlmeans/resource'
+import type { EntityResolverService, OrgEntityRef } from '@owlmeans/auth-common'
+import { ENTITY_RESOLVER, ENTITY_SLUG_PATTERN } from '@owlmeans/auth-common'
+import { generateWordSlug, nextSlugCandidate } from '@owlmeans/basic-ids'
+import type { OrgEntity, OrgEntityResource } from './types.js'
+import { AUTH_IDENTITY_ORG_ENTITY, MAX_ENTITY_SLUG_ATTEMPTS } from './consts.js'
+
+type Context = ServerContext<ServerConfig>
+
+/**
+ * How long a resolution is trusted without re-reading the registry.
+ *
+ * Every authenticated request resolves an entity, so an uncached resolver would put a database
+ * round-trip in front of the whole API. The cost of the cache is a rename taking up to this long
+ * to be seen by other replicas — which is survivable precisely because the old slug keeps
+ * resolving through `formerSlugs` rather than failing.
+ */
+const CACHE_TTL = 30_000
+
+/** A stored record as the contract exposes it. Persisted records always carry an id. */
+const toRef = (entity: OrgEntity | null): OrgEntityRef | null =>
+  entity == null ? null : {
+    id: entity.id!, slug: entity.slug, formerSlugs: entity.formerSlugs, iamKey: entity.iamKey,
+  }
+
+interface CacheEntry {
+  entity: OrgEntity | null
+  at: number
+}
+
+export const makeEntityResolverService = (
+  alias: string = ENTITY_RESOLVER
+): EntityResolverService => {
+  // Keyed by every name a caller might arrive with — id, slug, former slug, iamKey — so a hit
+  // costs one lookup regardless of which one it was.
+  const cache = new Map<string, CacheEntry>()
+  const now = () => Date.now()
+
+  const remember = (entity: OrgEntity | null, ...keys: string[]): OrgEntity | null => {
+    const at = now()
+    for (const key of keys) {
+      if (key !== '') cache.set(key, { entity, at })
+    }
+    if (entity != null) {
+      cache.set(entity.id!, { entity, at })
+      cache.set(entity.slug, { entity, at })
+      cache.set(entity.iamKey, { entity, at })
+      for (const former of entity.formerSlugs ?? []) cache.set(former, { entity, at })
+    }
+
+    return entity
+  }
+
+  const forget = (entity: OrgEntity) => {
+    for (const key of [entity.id, entity.slug, entity.iamKey, ...(entity.formerSlugs ?? [])]) {
+      if (key != null) cache.delete(key)
+    }
+  }
+
+  const resource = (): OrgEntityResource =>
+    (service.ctx as Context).resource<OrgEntityResource>(AUTH_IDENTITY_ORG_ENTITY)
+
+  const load = async (value: string): Promise<OrgEntity | null> => {
+    const cached = cache.get(value)
+    if (cached != null && now() - cached.at < CACHE_TTL) {
+      return cached.entity
+    }
+
+    const res = resource()
+    // Id first: an id is authoritative, so a slug that happens to look like some other entity's
+    // id can never shadow it. A value that is not a record id simply misses. Then the current
+    // slug, then the names it has retired, then the frozen key external systems still quote.
+    const byId = await res.load(value)
+    if (byId != null) return remember(byId, value)
+
+    const candidates: Criteria<OrgEntity>[] = [
+      { slug: value },
+      { formerSlugs: { $contains: [value] } },
+      { iamKey: value },
+    ]
+    for (const where of candidates) {
+      const found = await res.load(where)
+      if (found != null) return remember(found, value)
+    }
+
+    return remember(null, value)
+  }
+
+  const service: EntityResolverService = appendContextual<EntityResolverService>(alias, {
+    resolve: async value => toRef(await load(value)),
+
+    byId: async id => toRef(remember(await resource().load(id), id)),
+
+    mintSlug: async () => {
+      const res = resource()
+      // A word slug is picked from 2^22 pairs, so a collision is rare — but "rare" is not "never"
+      // once an installation has many organizations, and the numeric suffix keeps the readable
+      // name rather than rerolling into an unrelated one.
+      for (let attempt = 1; attempt <= MAX_ENTITY_SLUG_ATTEMPTS; ++attempt) {
+        const base = generateWordSlug()
+        for (let suffix = 1; suffix <= 3; ++suffix) {
+          const candidate = nextSlugCandidate(base, suffix)
+          const taken = await res.load({
+            $or: [{ slug: candidate }, { formerSlugs: { $contains: [candidate] } }],
+          })
+          if (taken == null) return candidate
+        }
+      }
+
+      throw new SyntaxError('entity:slug-exhausted')
+    },
+
+    rename: async (id, slug) => {
+      if (!ENTITY_SLUG_PATTERN.test(slug)) {
+        throw new SyntaxError(`entity:slug-malformed:${slug}`)
+      }
+
+      const res = resource()
+      const entity = await res.get(id)
+      if (entity.slug === slug) {
+        return toRef(entity)!
+      }
+
+      // A slug another entity has ever answered to cannot be taken: tokens and third-party records
+      // quoting it would start resolving to the wrong organization.
+      const taken = await res.load({
+        $or: [{ slug }, { formerSlugs: { $contains: [slug] } }],
+      })
+      if (taken != null && taken.id !== id) {
+        throw new SyntaxError(`entity:slug-taken:${slug}`)
+      }
+
+      forget(entity)
+      const formerSlugs = [...new Set([...(entity.formerSlugs ?? []), entity.slug])]
+        .filter(former => former !== slug)
+      const updated = await res.update({ ...entity, slug, formerSlugs, updatedAt: new Date() })
+
+      return toRef(remember(updated))!
+    },
+
+    mintName: async (id, key, mint) => {
+      const res = resource()
+      const entity = await res.get(id)
+      const existing = entity.names?.[key]
+      // Read-before-mint is what freezes the name: the second caller gets the first caller's
+      // answer, so a rename between the two cannot produce two names for one live resource.
+      if (existing != null && existing !== '') {
+        return existing
+      }
+
+      const minted = mint(toRef(entity)!)
+      forget(entity)
+      const updated = await res.update({
+        ...entity, names: { ...entity.names, [key]: minted }, updatedAt: new Date(),
+      })
+      remember(updated)
+
+      return updated.names?.[key] ?? minted
+    },
+  })
+
+  return service
+}

package/src/resource.ts

@@ -1,23 +1,53 @@
 import { makeMongoResource } from '@owlmeans/mongo-resource'
-import type { IdentityAccount, IdentityAccountResource, IdentityProfile, IdentityProfileResource, IdentityCredentials, IdentityCredentialsResource } from './types.js'
+import type { IdentityAccount, IdentityAccountResource, IdentityProfile, IdentityProfileResource, IdentityCredentials, IdentityCredentialsResource, OrgEntity, OrgEntityResource } from './types.js'
 import {
-  AUTH_IDENTITY_ACCOUNT, AUTH_IDENTITY_PROFILE, AUTH_IDENTITY_CREDENTIALS,
-  AUTH_IDENTITY_ACCOUNT_COLLECTION, AUTH_IDENTITY_PROFILE_COLLECTION, AUTH_IDENTITY_CREDENTIALS_COLLECTION
+  AUTH_IDENTITY_ACCOUNT, AUTH_IDENTITY_PROFILE, AUTH_IDENTITY_CREDENTIALS, AUTH_IDENTITY_ORG_ENTITY,
+  AUTH_IDENTITY_ACCOUNT_COLLECTION, AUTH_IDENTITY_PROFILE_COLLECTION, AUTH_IDENTITY_CREDENTIALS_COLLECTION,
+  AUTH_IDENTITY_ORG_ENTITY_COLLECTION
 } from './consts.js'
 
+/**
+ * The organization-entity registry.
+ *
+ * Both unique indexes are load-bearing. `slug` is what a rename writes, so the index is the only
+ * thing standing between two organizations and the same public name; `iamKey` is quoted by systems
+ * that were told it once and never asked again, so a duplicate there would silently hand one
+ * organization another's realm. `formerSlugs` is indexed but NOT unique-scoped as a set — a retired
+ * slug must stay findable, and uniqueness against it is enforced when a rename is applied.
+ */
+export const makeOrgEntityResource = (dbAlias?: string): OrgEntityResource => {
+  const resource = makeMongoResource<OrgEntity, OrgEntityResource>(
+    AUTH_IDENTITY_ORG_ENTITY, dbAlias, undefined, AUTH_IDENTITY_ORG_ENTITY_COLLECTION
+  )
+  resource.index('slug', { slug: 1 }, { unique: true })
+  resource.index('iamKey', { iamKey: 1 }, { unique: true })
+  resource.index('formerSlugs', { formerSlugs: 1 })
+  return resource
+}
+
 export const makeIdentityAccountResource = (dbAlias?: string): IdentityAccountResource => {
   const resource = makeMongoResource<IdentityAccount, IdentityAccountResource>(
-    AUTH_IDENTITY_ACCOUNT, dbAlias, undefined, undefined, AUTH_IDENTITY_ACCOUNT_COLLECTION
+    AUTH_IDENTITY_ACCOUNT, dbAlias, undefined, AUTH_IDENTITY_ACCOUNT_COLLECTION
   )
   resource.index('credential', { credential: 1 }, { unique: true })
   resource.index('entityId', { entityId: 1 })
   resource.index('secret', { secret: 1 }, { unique: true, sparse: true })
+  /**
+   * The account's login name — an email, for every provider shipped today.
+   *
+   * Indexed because `linkProfile` reads it on every registration: a person signing in by a second
+   * method must land on the identity they already have, not a new one. NOT unique — the same
+   * address legitimately appears twice, once for the platform account and once for an
+   * organization's END USER record (`inviteUser`), and those are different people-shaped rows for
+   * different audiences. The two are told apart by the profile, never by the account.
+   */
+  resource.index('name', { name: 1 })
   return resource
 }
 
 export const makeIdentityProfileResource = (dbAlias?: string): IdentityProfileResource => {
   const resource = makeMongoResource<IdentityProfile, IdentityProfileResource>(
-    AUTH_IDENTITY_PROFILE, dbAlias, undefined, undefined, AUTH_IDENTITY_PROFILE_COLLECTION
+    AUTH_IDENTITY_PROFILE, dbAlias, undefined, AUTH_IDENTITY_PROFILE_COLLECTION
   )
   /**
    * The account's mongo id — the ONLY ObjectId reference in the identity trio.
@@ -34,7 +64,7 @@ export const makeIdentityProfileResource = (dbAlias?: string): IdentityProfileRe
 
 export const makeIdentityCredentialsResource = (dbAlias?: string): IdentityCredentialsResource => {
   const resource = makeMongoResource<IdentityCredentials, IdentityCredentialsResource>(
-    AUTH_IDENTITY_CREDENTIALS, dbAlias, undefined, undefined, AUTH_IDENTITY_CREDENTIALS_COLLECTION
+    AUTH_IDENTITY_CREDENTIALS, dbAlias, undefined, AUTH_IDENTITY_CREDENTIALS_COLLECTION
   )
   resource.index('provider', { type: 1, userId: 1, credential: 1 }, { unique: true })
   resource.index('profileId', { profileId: 1 })

package/src/service.ts

@@ -4,8 +4,13 @@ import type { AuthCredentials, AuthPayload, Profile } from '@owlmeans/auth'
 import { ALL_SCOPES, AuthRole } from '@owlmeans/auth'
 import type { ProviderProfileDetails } from '@owlmeans/oidc'
 import { createIdOfLength, IdStyle } from '@owlmeans/basic-ids'
+import type { Criteria } from '@owlmeans/resource'
 import type { AccountMeta, IdentityAccountResource, IdentityProfileResource, IdentityCredentialsResource, IdentityLinkingService } from './types.js'
-import { AUTH_IDENTITY_ACCOUNT, AUTH_IDENTITY_PROFILE, AUTH_IDENTITY_CREDENTIALS, AUTH_IDENTITY_LINKING, LOGIN_SERVICE_PREFIX, EXTERNAL_KEY_DELIMITER } from './consts.js'
+import type { IdentityAccount, IdentityCredentials, IdentityProfile } from './types.js'
+import type { OrgEntity, OrgEntityResource } from './types.js'
+import type { EntityResolverService } from '@owlmeans/auth-common'
+import { ENTITY_RESOLVER } from '@owlmeans/auth-common'
+import { AUTH_IDENTITY_ACCOUNT, AUTH_IDENTITY_PROFILE, AUTH_IDENTITY_CREDENTIALS, AUTH_IDENTITY_LINKING, AUTH_IDENTITY_ORG_ENTITY, LOGIN_SERVICE_PREFIX, EXTERNAL_KEY_DELIMITER } from './consts.js'
 
 type Context = ServerContext<ServerConfig>
 
@@ -20,23 +25,73 @@ const loginService = (details: ProviderProfileDetails): string =>
   [LOGIN_SERVICE_PREFIX, details.type, details.service].join(EXTERNAL_KEY_DELIMITER)
 
 export const makeIdentityLinkingService = (): IdentityLinkingService => {
+  /**
+   * The wire value for a stored entity id.
+   *
+   * Records key on the id; everything this service hands back is an auth payload, and payloads
+   * carry the slug. An id that no longer resolves yields undefined rather than leaking the raw
+   * id onto the wire, where a consumer would mistake it for a slug and compose names from it.
+   */
+  const slugOf = async (entityId?: string): Promise<string | undefined> => {
+    if (entityId == null || entityId === '') return undefined
+    const ctx = service.ctx as Context
+    const entity = await ctx.service<EntityResolverService>(ENTITY_RESOLVER).byId(entityId)
+
+    return entity?.slug
+  }
+
+  /**
+   * The platform identity this person already has, if any.
+   *
+   * One human, one email, one profile — whichever way they sign in. Every provider that reaches
+   * `linkProfile` establishes the email first (Google asserts a verified address, the OTP flow
+   * proves possession of it, the supervisor key is a full-trust developer credential), so the
+   * name is the identity and a second method is a second CREDENTIAL on it, never a second person.
+   * Without this the platform minted a whole new organization per method: the same address signed
+   * in by Google and by key ended up in two entities, and each could see only the projects the
+   * other had not created.
+   *
+   * Two rows can carry one address, and only one of them is a platform login. `inviteUser`
+   * (`@owlmeans/iam-integrated`) writes an END USER record for the same person — the identity the
+   * GENERATED application authenticates, deliberately kept apart from the platform credential.
+   * Those rows carry no login service, which is what tells the two apart here: this service is
+   * the only writer of `credential = "service:{type}:{service}"`, so a profile that has one is a
+   * platform login and a profile that has none is somebody's end user.
+   */
+  const findPlatformIdentity = async (username: string): Promise<IdentityProfile | null> => {
+    const name = username.trim()
+    if (name === '') return null
+
+    const ctx = service.ctx as Context
+    const accountResource = ctx.resource<IdentityAccountResource>(AUTH_IDENTITY_ACCOUNT)
+    const profileResource = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
+
+    const { items: accounts } = await accountResource.list({ name } as Criteria<IdentityAccount>)
+    for (const account of accounts) {
+      const { items: profiles } = await profileResource.list({ userId: account.id } as Criteria<IdentityProfile>)
+      const platform = profiles.find(profile =>
+        profile.credential?.startsWith(`${LOGIN_SERVICE_PREFIX}${EXTERNAL_KEY_DELIMITER}`) === true
+      )
+      if (platform != null) return platform
+    }
+
+    return null
+  }
+
   const service: IdentityLinkingService = appendContextual<IdentityLinkingService>(AUTH_IDENTITY_LINKING, {
     getLinkedProfile: async (details: ProviderProfileDetails): Promise<AuthPayload | null> => {
       const ctx = service.ctx as Context
       const credsResource = ctx.resource<IdentityCredentialsResource>(AUTH_IDENTITY_CREDENTIALS)
 
-      const { items: creds } = await credsResource.list({
-        criteria: {
-          type: details.type,
-          userId: externalKey(details),
-          credential: loginService(details),
-        }
+      const cred = await credsResource.load({
+        type: details.type,
+        userId: externalKey(details),
+        credential: loginService(details),
       })
-      const cred = creds[0] ?? null
       if (cred == null) return null
 
       const profileResource = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
-      const profile = await profileResource.load(cred.profileId, 'profileId')
+      const profile = await profileResource.load({ profileId: cred.profileId })
       if (profile == null) return null
 
       return {
@@ -44,7 +99,7 @@ export const makeIdentityLinkingService = (): IdentityLinkingService => {
         role: profile.role,
         userId: profile.userId ?? profile.profileId,
         profileId: profile.profileId,
-        entityId: profile.entityId,
+        entitySlug: await slugOf(profile.entityId),
         scopes: profile.scopes,
       }
     },
@@ -54,20 +109,56 @@ export const makeIdentityLinkingService = (): IdentityLinkingService => {
       const accountResource = ctx.resource<IdentityAccountResource>(AUTH_IDENTITY_ACCOUNT)
       const profileResource = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
       const credsResource = ctx.resource<IdentityCredentialsResource>(AUTH_IDENTITY_CREDENTIALS)
+      const entityResource = ctx.resource<OrgEntityResource>(AUTH_IDENTITY_ORG_ENTITY)
+      const resolver = ctx.service<EntityResolverService>(ENTITY_RESOLVER)
+
+      // A person the platform already knows is LINKED, not registered again. Everything below
+      // this point creates an organization, an account and a profile, and doing that for a second
+      // login method is what put one email in two entities.
+      const known = meta.force === true ? null : await findPlatformIdentity(meta.username)
+      if (known != null) {
+        await credsResource.create({
+          challenge: '',
+          type: details.type,
+          userId: externalKey(details),
+          profileId: known.profileId,
+          credential: loginService(details),
+        })
+
+        return {
+          type: details.type,
+          role: known.role,
+          userId: known.userId ?? known.profileId,
+          profileId: known.profileId,
+          entitySlug: await slugOf(known.entityId),
+          scopes: known.scopes,
+        }
+      }
+
+      // Every account gets its own organization. The entity record is created FIRST because it
+      // owns the two values that outlive everything else here: the id the account and its profiles
+      // are keyed by, and the frozen `iamKey` that realms and object names are minted from.
+      const entity: OrgEntity = await entityResource.create({
+        slug: await resolver.mintSlug(),
+        formerSlugs: [],
+        // Frozen at birth and never recomputed. It cannot be the slug — the slug moves — and it
+        // cannot be the record id, which does not exist until this create returns.
+        iamKey: createIdOfLength(16, IdStyle.Base58),
+        names: {},
+        createdAt: new Date(),
+      })
+      const entityId = entity.id!
 
-      // Generate a unique local entity slug stored as the account credential.
       let accountId: string | null = null
-      let entityId: string | null = null
       for (let i = 0; i < MAX_SLUG_RETRIES; i++) {
         const credential = createIdOfLength(16, IdStyle.Base58)
         try {
           const account = await accountResource.create({
             credential,
             name: meta.username,
-            entityId: credential,
+            entityId,
           })
           accountId = account.id
-          entityId = account.credential
           break
         } catch (err: any) {
           if (err?.code === 11000 || err?.message?.includes('duplicate')) continue
@@ -75,7 +166,7 @@ export const makeIdentityLinkingService = (): IdentityLinkingService => {
         }
       }
 
-      if (accountId == null || entityId == null) {
+      if (accountId == null) {
         throw new Error('Failed to generate unique account credential after retries')
       }
 
@@ -95,7 +186,7 @@ export const makeIdentityLinkingService = (): IdentityLinkingService => {
         })
       } catch (err: any) {
         if (err?.code === 11000 || err?.message?.includes('duplicate')) {
-          profile = await profileResource.get(profileId, 'profileId')
+          profile = await profileResource.get({ profileId })
         } else {
           throw err
         }
@@ -114,7 +205,7 @@ export const makeIdentityLinkingService = (): IdentityLinkingService => {
         role: profile.role,
         userId: profile.userId ?? profile.profileId,
         profileId: profile.profileId,
-        entityId: profile.entityId,
+        entitySlug: await slugOf(profile.entityId),
         scopes: profile.scopes,
       }
     },
@@ -140,21 +231,33 @@ export const makeIdentityLinkingService = (): IdentityLinkingService => {
       return result
     },
 
+    unlinkCredentials: async (details: ProviderProfileDetails): Promise<void> => {
+      const ctx = service.ctx as Context
+      const credsResource = ctx.resource<IdentityCredentialsResource>(AUTH_IDENTITY_CREDENTIALS)
+      const cred = await credsResource.load({
+        type: details.type,
+        userId: externalKey(details),
+        credential: loginService(details),
+      })
+      if (cred?.id == null) return
+      await credsResource.delete(cred.id)
+    },
+
     getOwnerProfiles: async (entityId: string): Promise<Profile[]> => {
       const ctx = service.ctx as Context
       const profileResource = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
-      const { items: profiles } = await profileResource.list({ criteria: { entityId } })
+      const { items: profiles } = await profileResource.list({ entityId })
 
-      return profiles.map(p => ({
+      return await Promise.all(profiles.map(async p => ({
         id: p.profileId,
         name: p.name,
         credential: p.credential,
-        entityId: p.entityId,
+        entitySlug: await slugOf(p.entityId),
         scopes: p.scopes,
         groups: p.groups,
         permissions: p.permissions,
         attributes: p.attributes,
-      }))
+      })))
     },
 
     getOwnerCredentials: async (userId: string, entityId?: string, type?: string): Promise<AuthCredentials | undefined> => {
@@ -162,19 +265,18 @@ export const makeIdentityLinkingService = (): IdentityLinkingService => {
       const profileResource = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
       const credsResource = ctx.resource<IdentityCredentialsResource>(AUTH_IDENTITY_CREDENTIALS)
 
-      const profileFilter: Record<string, unknown> = { userId }
+      const profileFilter: Criteria<IdentityProfile> = { userId }
       if (entityId != null) profileFilter.entityId = entityId
-      const { items: profiles } = await profileResource.list(profileFilter as any)
+      const { items: profiles } = await profileResource.list(profileFilter)
       if (profiles.length === 0) return undefined
 
-      const credsFilter: Record<string, unknown> = {
+      const credsFilter: Criteria<IdentityCredentials> = {
         profileId: { $in: profiles.map(p => p.profileId) }
       }
       if (type != null) credsFilter.type = type
-      const { items: creds } = await credsResource.list(credsFilter as any)
-      if (creds.length === 0) return undefined
+      const cred = await credsResource.load(credsFilter)
+      if (cred == null) return undefined
 
-      const cred = creds[0]
       const profile = profiles.find(p => p.profileId === cred.profileId) ?? profiles[0]
 
       return {
@@ -182,7 +284,7 @@ export const makeIdentityLinkingService = (): IdentityLinkingService => {
         role: profile.role,
         userId: profile.userId ?? profile.profileId,
         profileId: profile.profileId,
-        entityId: profile.entityId,
+        entitySlug: await slugOf(profile.entityId),
         scopes: profile.scopes,
         challenge: cred.challenge,
         credential: cred.credential,

package/src/types.ts

@@ -7,23 +7,29 @@ import type { ProviderProfileDetails } from '@owlmeans/oidc'
 
 /**
  * Local account record — one per user.
- * id is the Mongo resource id; credential is the stable unique local entity slug.
+ *
+ * `id` is the Mongo resource id; `credential` is the account's stable unique key. `entityId`
+ * (inherited from Profile below) holds the organization entity's record id — never its slug.
  */
-export interface IdentityAccount extends Profile, ResourceRecord {
+export interface IdentityAccount extends Omit<Profile, 'entitySlug'>, ResourceRecord {
   id: string
   credential: string
+  /** Stable organization-entity id. Renaming the organization does not touch this. */
+  entityId?: string
 }
 
 /**
  * Local profile record — ties a user to an entity with a role.
  * Mirrors IAMProfile from @owlmeans/auth backend.
  */
-export interface IdentityProfile extends Profile, ResourceRecord {
+export interface IdentityProfile extends Omit<Profile, 'entitySlug'>, ResourceRecord {
   id: string
   profileId: string
   userId?: string
   role: AuthRole
   expiresAt?: Date
+  /** Stable organization-entity id — the value every per-organization query filters on. */
+  entityId?: string
 }
 
 /**
@@ -36,6 +42,29 @@ export interface IdentityCredentials extends AuthCredentials, ResourceRecord {
   profileId: string
 }
 
+/**
+ * An organization entity — the record every per-organization store keys on.
+ *
+ * Its `id` is the stable entity id. The slug is the value users, URLs and tokens see, and it may
+ * move; nothing here except `slug` itself changes when it does, which is the entire point of the
+ * record existing.
+ */
+export interface OrgEntity extends ResourceRecord {
+  id?: string
+  slug: string
+  formerSlugs?: string[]
+  iamKey: string
+  /**
+   * Names this organization is known by in systems that cannot rename: a Kubernetes namespace, a
+   * storage prefix, an IAM realm. Minted once through `mintName` and read back forever after.
+   */
+  names?: Record<string, string>
+  createdAt: Date
+  updatedAt?: Date
+}
+
+export type OrgEntityResource = MongoResource<OrgEntity>
+
 export type IdentityAccountResource = MongoResource<IdentityAccount>
 export type IdentityProfileResource = MongoResource<IdentityProfile>
 export type IdentityCredentialsResource = MongoResource<IdentityCredentials>
@@ -48,6 +77,17 @@ export interface IdentityLinkingService extends InitializedService {
   getLinkedProfile: (details: ProviderProfileDetails) => Promise<AuthPayload | null>
   linkProfile: (details: ProviderProfileDetails, meta: AccountMeta) => Promise<AuthPayload>
   linkCredentials: (details: ProviderProfileDetails) => Promise<AuthPayload>
+  /**
+   * Forget which profile an external login maps to, so the next `linkProfile` establishes it anew.
+   *
+   * The stored mapping is keyed `{type, userId, credential}` under a unique index, so a caller
+   * that has decided the existing mapping is wrong cannot simply write over it — it has to be
+   * retired first. That decision belongs to whoever owns the login path (a decorator serving a
+   * different population than the platform's own customers, say); the key format belongs here.
+   *
+   * Idempotent: a login that maps to nothing is already in the state this promises.
+   */
+  unlinkCredentials: (details: ProviderProfileDetails) => Promise<void>
   getOwnerProfiles: (entityId: string) => Promise<Profile[]>
   getOwnerCredentials: (userId: string, entityId?: string, type?: string) => Promise<AuthCredentials | undefined>
 }