@happyvertical/smrt-profiles 0.39.13 → 0.39.15

package/dist/oidc-provisioning.d.ts

@@ -0,0 +1,83 @@
+import { getDatabase } from '@happyvertical/sql';
+
+/**
+ * Coordinate one OIDC provisioning operation across adapters.
+ *
+ * Root adapters must expose `beginTransaction`. Already-bound adapters must
+ * support savepoints. An adapter that exposes only `transaction()` is
+ * intentionally ambiguous and fails closed instead of risking a nested
+ * transaction that could roll back its caller's work.
+ */
+export declare function coordinateOidcProvisioning<T>(options: OidcProvisioningCoordinatorOptions<T>): Promise<T>;
+
+/**
+ * Trusted integration surface for framework packages participating in the
+ * owner-aware OIDC provisioning transaction.
+ *
+ * Application code should use UserCollection.getOrCreateFromOidc() instead.
+ * The generic result avoids duplicating nominal SMRT model declarations across
+ * package entry bundles; trusted callers bind it to the root package model.
+ */
+export declare function createOidcProvisioningPerson<TProfile>(db: DatabaseInterface, input: OidcProvisioningPersonInput): Promise<TProfile>;
+
+declare type DatabaseInterface = Awaited<ReturnType<typeof getDatabase>>;
+
+declare type DatabaseInterface_2 = Awaited<ReturnType<typeof getDatabase>>;
+
+/** Trusted integration insert after the caller proves Profile ownership. */
+export declare function insertOidcProvisioningIdentity<TIdentity>(db: DatabaseInterface, input: OidcProvisioningIdentityInput): Promise<TIdentity>;
+
+/** Detect an adapter error caused by an aborted transaction. */
+export declare function isOidcAbortedTransactionError(error: unknown): boolean;
+
+/** Classify only the durable constraints used to converge OIDC retries. */
+export declare function isOidcProvisioningRaceConflict(error: unknown, options?: OidcProvisioningRaceClassifierOptions): boolean;
+
+/** Shared transaction and concurrency policy for OIDC provisioning. */
+export declare interface OidcProvisioningCoordinatorOptions<T> {
+    /** Root or transaction-bound database used for every provisioning write. */
+    db: DatabaseInterface_2;
+    /**
+     * Stable keys used for local serialization. Supply both the exact
+     * issuer/subject key and normalized email when available.
+     */
+    lockKeys: readonly string[];
+    /** Package-specific durable race-arbiter classifier. */
+    isRaceConflict: (error: unknown) => boolean;
+    /** Package-specific transaction failure mapping. */
+    createTransactionError: (message: string, cause?: unknown) => Error;
+    /** Package-specific terminal concurrency failure mapping. */
+    createConcurrencyError: (cause?: unknown) => Error;
+    /** Provision atomically using the supplied transaction-bound handle. */
+    provision: (tx: DatabaseInterface_2) => Promise<T>;
+    /**
+     * Rehydrate root-owned results after commit so models do not retain a
+     * released transaction client. Omit for non-model results.
+     */
+    rebindRootResult?: (result: T, rootDb: DatabaseInterface_2) => Promise<T>;
+}
+
+export declare interface OidcProvisioningIdentityInput {
+    email?: string;
+    issuer: string;
+    profileId: string;
+    provider: string;
+    subject: string;
+}
+
+export declare interface OidcProvisioningPersonInput {
+    email?: string;
+    name?: string;
+    preferredUsername?: string;
+    subject: string;
+}
+
+export declare interface OidcProvisioningRaceClassifierOptions {
+    /** Package-specific database constraint messages. */
+    messagePatterns?: readonly RegExp[];
+}
+
+/** Wrap a known OIDC arbiter write so only its unique failure is retryable. */
+export declare function saveOidcRaceArbiter<T>(operation: () => Promise<T>): Promise<T>;
+
+export { }

package/dist/smrt-knowledge.json

@@ -1,17 +1,18 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-14T00:02:10.693Z",
+  "generatedAt": "2026-07-14T05:50:21.948Z",
   "packageName": "@happyvertical/smrt-profiles",
-  "packageVersion": "0.39.13",
+  "packageVersion": "0.39.15",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "98d5fb36812652e9acde14983db85de7a5287ef88264554a643e6f1053653508",
-    "packageJson": "ec110706c3d6e6465ecd631793d1967255ff754c23762cbbacbbaab344b5839a",
-    "agents": "3c18e895a2e065f761aabf31779c71a138f0a75261ab223464c3b2a5fbbe6b16"
+    "manifest": "d3eedfb2b0a6cf1292a59c90b9f57a649de709433363226ae9de236b48d3372f",
+    "packageJson": "7e39df481904d091e911f65035f618f2c7b9dd7e4a8fc726e70f596c7b15b33e",
+    "agents": "97e18475c8dba05b1f8811457c02bbfe98fbca30988476605cffbf189a13290d"
   },
   "exports": [
     ".",
+    "./internal/oidc-provisioning",
     "./manifest",
     "./manifest.json",
     "./utils"
@@ -184,6 +185,23 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "OidcProfileEmailReservationCollection",
+      "qualifiedName": "@happyvertical/smrt-profiles:OidcProfileEmailReservationCollection",
+      "collection": "oidcprofileemailreservations",
+      "tableName": "oidc_profile_email_reservations",
+      "packageName": "@happyvertical/smrt-profiles",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "ProfileAssetCollection",
       "qualifiedName": "@happyvertical/smrt-profiles:ProfileAssetCollection",
@@ -229,10 +247,13 @@
         "findByType",
         "findGlobal",
         "findRelated",
+        "findUniqueGlobalPersonByEmail",
         "findWithGlobals",
         "getAssets",
         "getRelationshipNetwork",
-        "removeAsset"
+        "removeAsset",
+        "requireCanonicalGlobalPerson",
+        "reserveCanonicalIdentityEmail"
       ],
       "surfaces": [],
       "relationshipFeatures": [
@@ -358,7 +379,8 @@
       "relationships": [],
       "methods": [
         "getBySlug",
-        "getOrCreateBySlug"
+        "getOrCreateBySlug",
+        "getOrCreateGlobalBySlug"
       ],
       "surfaces": [],
       "relationshipFeatures": [
@@ -953,6 +975,12 @@
           "required": false,
           "columnType": "TEXT"
         },
+        {
+          "name": "identityKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "email",
           "type": "text",
@@ -976,10 +1004,12 @@
         }
       ],
       "methods": [
+        "buildIdentityKey",
         "findBySubject",
         "findOrCreate",
         "getProfile",
-        "recordUsage"
+        "recordUsage",
+        "save"
       ],
       "surfaces": [
         {
@@ -998,22 +1028,6 @@
           "path": "/oidcidentities/[id]",
           "method": "GET"
         },
-        {
-          "kind": "api",
-          "name": "oidcidentities.create",
-          "operation": "create",
-          "objectName": "@happyvertical/smrt-profiles:OidcIdentity",
-          "path": "/oidcidentities",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "oidcidentities.update",
-          "operation": "update",
-          "objectName": "@happyvertical/smrt-profiles:OidcIdentity",
-          "path": "/oidcidentities/[id]",
-          "method": "PATCH"
-        },
         {
           "kind": "cli",
           "name": "oidcidentity_list",
@@ -1046,6 +1060,46 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "OidcProfileEmailReservation",
+      "qualifiedName": "@happyvertical/smrt-profiles:OidcProfileEmailReservation",
+      "collection": "oidcprofileemailreservations",
+      "tableName": "oidc_profile_email_reservations",
+      "packageName": "@happyvertical/smrt-profiles",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "profileId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "emailKey",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "profileId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "Profile",
       "qualifiedName": "@happyvertical/smrt-profiles:Profile",
@@ -1085,6 +1139,12 @@
           "required": false,
           "columnType": "TEXT"
         },
+        {
+          "name": "emailKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "name",
           "type": "text",
@@ -2542,6 +2602,12 @@
           "required": false,
           "columnType": "TEXT"
         },
+        {
+          "name": "emailKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "name",
           "type": "text",
@@ -2719,6 +2785,12 @@
           "required": false,
           "columnType": "TEXT"
         },
+        {
+          "name": "emailKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "name",
           "type": "text",
@@ -2896,6 +2968,12 @@
           "required": false,
           "columnType": "TEXT"
         },
+        {
+          "name": "emailKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "name",
           "type": "text",
@@ -3254,22 +3332,6 @@
       "path": "/oidcidentities/[id]",
       "method": "GET"
     },
-    {
-      "kind": "api",
-      "name": "oidcidentities.create",
-      "operation": "create",
-      "objectName": "@happyvertical/smrt-profiles:OidcIdentity",
-      "path": "/oidcidentities",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "oidcidentities.update",
-      "operation": "update",
-      "objectName": "@happyvertical/smrt-profiles:OidcIdentity",
-      "path": "/oidcidentities/[id]",
-      "method": "PATCH"
-    },
     {
       "kind": "cli",
       "name": "oidcidentity_list",
@@ -3855,12 +3917,12 @@
     }
   ],
   "relationshipsV2": {
-    "foreignKeyFields": 18,
+    "foreignKeyFields": 19,
     "crossPackageRefFields": 1,
     "junctionCollections": 1,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 58
+    "uuidColumns": 61
   },
-  "agentDoc": "# @happyvertical/smrt-profiles\n\nCentral identity system with multi-auth, relationships, controlled metadata, and audit logging.\n\n## Models\n\n- **Profile** (STI base → Bot, Organization, Person): email (globally unique), `typeId` FK to ProfileType, plus a `metadata` `@oneToMany('ProfileMetadata')` relationship for controlled per-profile values.\n- **ProfileAsset**: dedicated owned-asset join in `profile_assets` with `relationship` and `sortOrder`.\n- **ProfileRelationship**: bidirectional — creating one auto-creates reciprocal inverse. `contextProfileId` for tertiary relationships. `ProfileRelationshipTerm` tracks start/end dates.\n- **ProfileMetafield**: controlled vocabulary with `validationSchema`. **ProfileMetadata**: per-profile values linked to metafields.\n- **AuditLog**: action, resourceType/Id, `source` (web/cli/ci/webhook/mcp), `onBehalfOfId` for CI pass-through identity. `allowSuperAdminBypass: true`.\n\n## Auth Methods\n\n| Model | Pattern |\n|-------|---------|\n| NostrIdentity | Encrypted keypair (AES-256-GCM). Requires `SERVER_MASTER_SECRET` env var for decryption. NIP-05 address generation. |\n| OidcIdentity | Multiple issuers (Keycloak/Google/GitHub). Lookup by `issuer + subject` pair. `findOrCreate()` for first login. |\n| ApiKey | SHA-256 hashed. **Plaintext returned once only** on `generate()`. `keyPrefix` for identification. Scope-based with expiry. |\n| MagicLinkToken | One-time token with expiry for passwordless auth. |\n\n## Identity Resolution\n\nAuth helpers in `src/auth/` build profiles from external identity claims:\n\n- `resolveIdentity()` — top-level dispatcher that returns/creates a Profile from Nostr signatures, OIDC claims, magic link tokens, or API keys.\n- `createProfileFromOidc(claims, provider)` — creates `Profile` + `OidcIdentity` for first-time OIDC sign-in.\n- `createProfileFromNostr(email, nostrData)` — creates `Profile` + `NostrIdentity` for Nostr-authenticated users.\n\n## Key Methods\n\n- `Profile.getAssets()` / `addAsset()` / `removeAsset()` and the matching `ProfileCollection` wrappers — canonical owned asset helpers backed by `profile_assets`.\n- `Profile.addMetadata(metafieldSlug, value)` / `Profile.getMetadata()` — validates against metafield schema. `ProfileCollection.batchGetMetadata()` / `batchUpdateMetadata()` for bulk reads/writes.\n- `Profile.getRelationships({ direction: 'from'|'to'|'all' })` — direction matters.\n- `Profile.getRelationshipsFrom()` / `getRelationshipsTo()` — R10-generated `@oneToMany` accessors. ProfileRelationship has two FKs back to Profile, so each `@oneToMany` annotates its inverse explicitly (`{ foreignKey: 'fromProfileId' }` / `'toProfileId'`). Return raw `ProfileRelationship[]`; use `getRelationships()` for slug/direction filtering.\n- AI: `generateBio()` (uses `smrtProfiles.profile.generateBio` prompt via `@happyvertical/smrt-prompts`), `matches(criteria)` (delegates to `is()`).\n\n## Prompt Registry\n\n`generateBio()` is registered with `@happyvertical/smrt-prompts` so tenants can override template/model/params at runtime:\n\n```typescript\nimport { smrtProfilesGenerateBioPrompt } from '@happyvertical/smrt-profiles';\n// key: 'smrtProfiles.profile.generateBio'\n```\n\n## Gotchas\n\n- **SERVER_MASTER_SECRET required** for Nostr private key decryption — centralized key management\n- **API key never returned again**: `ApiKey.generate()` returns plaintext once; only `keyPrefix` visible later\n- **OIDC unique per issuer+subject**: same subject from different issuers = different identities\n- **Email unique across all profiles**: DB-level unique constraint, not per-tenant\n- **Optional tenancy** on Profile; AuditLog allows super-admin bypass\n"
+  "agentDoc": "# @happyvertical/smrt-profiles\n\nCentral identity system with multi-auth, relationships, controlled metadata, and audit logging.\n\n## Models\n\n- **Profile** (STI base → Bot, Organization, Person): email (globally unique exact value), readonly indexed `emailKey` derived with `normalizeIdentityEmail()` for adapter-independent identity lookup, `typeId` FK to ProfileType, plus a `metadata` `@oneToMany('ProfileMetadata')` relationship for controlled per-profile values.\n- **ProfileAsset**: dedicated owned-asset join in `profile_assets` with `relationship` and `sortOrder`.\n- **ProfileRelationship**: bidirectional — creating one auto-creates reciprocal inverse. `contextProfileId` for tertiary relationships. `ProfileRelationshipTerm` tracks start/end dates.\n- **ProfileMetafield**: controlled vocabulary with `validationSchema`. **ProfileMetadata**: per-profile values linked to metafields.\n- **AuditLog**: action, resourceType/Id, `source` (web/cli/ci/webhook/mcp), `onBehalfOfId` for CI pass-through identity. `allowSuperAdminBypass: true`.\n\n## Auth Methods\n\n| Model | Pattern |\n|-------|---------|\n| NostrIdentity | Encrypted keypair (AES-256-GCM). Requires `SERVER_MASTER_SECRET` env var for decryption. NIP-05 address generation. |\n| OidcIdentity | Multiple issuers (Keycloak/Google/GitHub). Lookup by `issuer + subject` pair. Transactional provisioning derives the readonly nullable unique `identityKey` and backfills legacy rows. |\n| ApiKey | SHA-256 hashed. **Plaintext returned once only** on `generate()`. `keyPrefix` for identification. Scope-based with expiry. |\n| MagicLinkToken | One-time token with expiry for passwordless auth. |\n\n## Identity Resolution\n\nAuth helpers in `src/auth/` build profiles from external identity claims:\n\n- `resolveIdentity()` — top-level dispatcher that returns/creates a Profile from Nostr signatures, OIDC claims, magic link tokens, or API keys.\n- `createProfileFromOidc(claims, provider, options)` — creates `Profile` + `OidcIdentity` for first-time OIDC sign-in using a transaction-capable root database in `options.db`.\n- `ProfileCollection.findUniqueGlobalPersonByEmail(email)` — supported\n  verified-identity lookup; fails closed on tenant-scoped, non-Person, or\n  duplicate case-insensitive matches.\n- `ProfileCollection.requireCanonicalGlobalPerson(profileId, email?)` —\n  validates an application-selected Profile against the same canonical global\n  Person invariant.\n- `ProfileCollection.reserveCanonicalIdentityEmail(profileId, email?)` —\n  validates and synchronizes the private unique\n  `oidc_profile_email_reservations.email_key` used as the database arbiter for\n  concurrent external-identity provisioning. Omitting `email` uses the\n  Profile's stored address, moving or removing an existing reservation as the\n  canonical Profile changes.\n- `createProfileFromNostr(email, nostrData)` — creates `Profile` + `NostrIdentity` for Nostr-authenticated users.\n\n## Key Methods\n\n- `Profile.getAssets()` / `addAsset()` / `removeAsset()` and the matching `ProfileCollection` wrappers — canonical owned asset helpers backed by `profile_assets`.\n- `Profile.addMetadata(metafieldSlug, value)` / `Profile.getMetadata()` — validates against metafield schema. `ProfileCollection.batchGetMetadata()` / `batchUpdateMetadata()` for bulk reads/writes.\n- `Profile.getRelationships({ direction: 'from'|'to'|'all' })` — direction matters.\n- `Profile.getRelationshipsFrom()` / `getRelationshipsTo()` — R10-generated `@oneToMany` accessors. ProfileRelationship has two FKs back to Profile, so each `@oneToMany` annotates its inverse explicitly (`{ foreignKey: 'fromProfileId' }` / `'toProfileId'`). Return raw `ProfileRelationship[]`; use `getRelationships()` for slug/direction filtering.\n- AI: `generateBio()` (uses `smrtProfiles.profile.generateBio` prompt via `@happyvertical/smrt-prompts`), `matches(criteria)` (delegates to `is()`).\n\n## Prompt Registry\n\n`generateBio()` is registered with `@happyvertical/smrt-prompts` so tenants can override template/model/params at runtime:\n\n```typescript\nimport { smrtProfilesGenerateBioPrompt } from '@happyvertical/smrt-profiles';\n// key: 'smrtProfiles.profile.generateBio'\n```\n\n## Gotchas\n\n- **SERVER_MASTER_SECRET required** for Nostr private key decryption — centralized key management\n- **API key never returned again**: `ApiKey.generate()` returns plaintext once; only `keyPrefix` visible later\n- **OIDC unique per issuer+subject**: same subject from different issuers =\n  different identities. Both claims are opaque and case-sensitive; preserve\n  exact whitespace after using trim only to reject blank values.\n- **OIDC identity mutations are trusted-only**: generated REST, MCP, and CLI\n  surfaces are read-only. Link or update identities through transactional\n  provisioning APIs so callers cannot rebind issuer/subject authority to an\n  arbitrary Profile. Deprecated `OidcIdentity.findOrCreate()` preserves only\n  transaction-safe exact-link reuse and refuses to create new links;\n  `OidcIdentityCollection.linkToProfile()` and `Profile.linkOidcIdentity()`\n  delegate to that same non-creating compatibility path.\n- **Apply schema migrations for identity race keys**: run `smrt db:status`,\n  `smrt db:migrate`, then `smrt db:status` before deploying. Transactional OIDC\n  provisioning populates `OidcIdentity.identityKey` and\n  `oidc_profile_email_reservations`; legacy rows reserve an address only after\n  safe validation. Stop/upgrade old Profile writers, then run the public,\n  transactional and idempotent `backfillProfileEmailKeys(db)` from one deploy\n  process. Verified-email provisioning and public email-key lookup require the\n  standard `_smrt_backfills` readiness marker and fail closed immediately when\n  it is absent. This keeps table scans in the explicit deploy step; runtime\n  reads use the indexed key and validate only returned candidates.\n- **Public OIDC provisioning requires transactions**:\n  `createProfileFromOidc()` owns a root transaction or uses a savepoint on an\n  already-bound handle. Root adapters must expose `beginTransaction`;\n  transaction-only handles are ambiguous and fail closed. Pass the root\n  database for adapters without nested savepoints, including DuckDB;\n  provisioning fails before durable writes if neither path is safe. Trusted\n  framework packages use the private\n  `@happyvertical/smrt-profiles/internal/oidc-provisioning` subpath instead of\n  duplicating adapter probing, locking, or retry policy, and supply both exact\n  issuer/subject and normalized-email lock keys in deterministic order. The\n  coordinator additionally serializes all SQLite/DuckDB provisioning\n  transactions per database URL because those adapters cannot overlap\n  unrelated root transactions safely and retries bounded PostgreSQL\n  deadlock/serialization failures. New OIDC Profiles use per-profile,\n  non-semantic slugs so duplicate display names never invoke natural-key upsert.\n  Caller-owned transactions never execute `_smrt_backfills` DDL; paths that\n  perform canonical email lookup or reservation require the table to already\n  exist or the caller must retry with the root database. Exact issuer/subject\n  reuse skips the email-key readiness-marker lookup, but root coordination still\n  initializes the shared tracker table. Caller-owned exact reuse does not\n  consult the tracker and therefore does not require that table.\n- **Profile-only OIDC linking fails closed on existing email matches**:\n  `createProfileFromOidc()` preserves exact issuer/subject reuse, including\n  legacy tenant-scoped and non-Person links, but profiles cannot prove whether a\n  User owns a same-email Profile. New identities therefore never attach to an\n  existing email match through this helper; User/session provisioning still\n  rejects unsafe linked Profiles before creating authentication state. Use\n  `UserCollection.getOrCreateFromOidc()` for owner-aware verified-email reuse and\n  its supported transaction-bound resolver hook.\n- **Email storage and identity matching differ**: `Profile.email` has an\n  exact-value DB constraint. Identity boundaries query readonly indexed\n  `Profile.emailKey`, derived by the shared TypeScript\n  `normalizeIdentityEmail()` helper rather than adapter-specific SQL casing or\n  trimming, and deliberately fail closed on duplicate normalized keys.\n- **Optional tenancy** on Profile; AuditLog allows super-admin bypass\n"
 }

package/dist/types.d.ts

@@ -270,6 +270,14 @@ declare class OidcIdentity extends SmrtObject {
      * OIDC subject claim - unique identifier from the provider
      */
     subject: string;
+    /**
+     * Stable issuer+subject key used as the database race arbiter.
+     *
+     * Nullable for legacy rows; every newly linked or reused identity backfills
+     * it. A separate unique constraint makes concurrent first login fail with a
+     * retryable conflict instead of creating two identities.
+     */
+    identityKey: string | null;
     /**
      * Cached email from the IdP (for display/lookup)
      */
@@ -287,8 +295,17 @@ declare class OidcIdentity extends SmrtObject {
      * Find identity by issuer and subject
      */
     static findBySubject(issuer: string, subject: string, options?: SmrtObjectOptions): Promise<OidcIdentity | null>;
+    /** Build the collision-free natural key for one OIDC issuer subject. */
+    static buildIdentityKey(issuer: string, subject: string): string;
+    /** Keep the durable key derived from its natural-key source fields. */
+    save(): Promise<this>;
     /**
-     * Find or create identity for a profile
+     * Reuse an existing exact identity for its unchanged Profile.
+     *
+     * @deprecated Authentication links must be created through transactional
+     * provisioning. This compatibility method only refreshes a unique mapping
+     * that already belongs to the supplied Profile, including legacy Profile
+     * types, and deliberately refuses to create or rebind authority.
      */
     static findOrCreate(profile: Profile, oidcData: {
         provider: string;
@@ -315,12 +332,16 @@ declare class Profile extends SmrtObject {
     tenantId: string | null;
     typeId?: string;
     email?: string;
+    /** Adapter-independent identity lookup key derived from email on save. */
+    emailKey: string | null;
     name: string;
     description?: string;
     metadata: ProfileMetadata[];
     relationshipsFrom: ProfileRelationship[];
     relationshipsTo: ProfileRelationship[];
     constructor(options?: ProfileOptions);
+    /** Keep the durable identity key derived from the public email field. */
+    save(): Promise<this>;
     /**
      * Get the profile type slug for this profile
      *
@@ -472,10 +493,13 @@ declare class Profile extends SmrtObject {
      */
     getOidcIdentities(): Promise<OidcIdentity[]>;
     /**
-     * Link a new OIDC identity to this profile
+     * Reuse an existing exact OIDC identity for this unchanged Profile.
      *
      * @param oidcData - OIDC provider data
      * @returns The linked OIDC identity record
+     * @deprecated New authentication links require owner-aware transactional
+     * provisioning. This compatibility helper may refresh a legacy Profile
+     * type, but refuses to create or rebind authority.
      */
     linkOidcIdentity(oidcData: {
         provider: string;

package/dist/utils.d.ts

@@ -302,6 +302,14 @@ declare class OidcIdentity extends SmrtObject {
      * OIDC subject claim - unique identifier from the provider
      */
     subject: string;
+    /**
+     * Stable issuer+subject key used as the database race arbiter.
+     *
+     * Nullable for legacy rows; every newly linked or reused identity backfills
+     * it. A separate unique constraint makes concurrent first login fail with a
+     * retryable conflict instead of creating two identities.
+     */
+    identityKey: string | null;
     /**
      * Cached email from the IdP (for display/lookup)
      */
@@ -319,8 +327,17 @@ declare class OidcIdentity extends SmrtObject {
      * Find identity by issuer and subject
      */
     static findBySubject(issuer: string, subject: string, options?: SmrtObjectOptions): Promise<OidcIdentity | null>;
+    /** Build the collision-free natural key for one OIDC issuer subject. */
+    static buildIdentityKey(issuer: string, subject: string): string;
+    /** Keep the durable key derived from its natural-key source fields. */
+    save(): Promise<this>;
     /**
-     * Find or create identity for a profile
+     * Reuse an existing exact identity for its unchanged Profile.
+     *
+     * @deprecated Authentication links must be created through transactional
+     * provisioning. This compatibility method only refreshes a unique mapping
+     * that already belongs to the supplied Profile, including legacy Profile
+     * types, and deliberately refuses to create or rebind authority.
      */
     static findOrCreate(profile: Profile, oidcData: {
         provider: string;
@@ -347,12 +364,16 @@ declare class Profile extends SmrtObject {
     tenantId: string | null;
     typeId?: string;
     email?: string;
+    /** Adapter-independent identity lookup key derived from email on save. */
+    emailKey: string | null;
     name: string;
     description?: string;
     metadata: ProfileMetadata[];
     relationshipsFrom: ProfileRelationship[];
     relationshipsTo: ProfileRelationship[];
     constructor(options?: ProfileOptions);
+    /** Keep the durable identity key derived from the public email field. */
+    save(): Promise<this>;
     /**
      * Get the profile type slug for this profile
      *
@@ -504,10 +525,13 @@ declare class Profile extends SmrtObject {
      */
     getOidcIdentities(): Promise<OidcIdentity[]>;
     /**
-     * Link a new OIDC identity to this profile
+     * Reuse an existing exact OIDC identity for this unchanged Profile.
      *
      * @param oidcData - OIDC provider data
      * @returns The linked OIDC identity record
+     * @deprecated New authentication links require owner-aware transactional
+     * provisioning. This compatibility helper may refresh a legacy Profile
+     * type, but refuses to create or rebind authority.
      */
     linkOidcIdentity(oidcData: {
         provider: string;

package/dist/utils.js

@@ -1,17 +1,17 @@
 //#region src/utils.ts
 async function getProfileMetadata(profileId, options = {}) {
-	const { ProfileMetadataCollection } = await import("./chunks/ProfileMetadataCollection-CGcO4Iw_.js").then((n) => n.n);
+	const { ProfileMetadataCollection } = await import("./chunks/ProfileMetadataCollection-loKVv_pj.js").then((n) => n.n);
 	return await (await ProfileMetadataCollection.create(options)).getMetadataObject(profileId);
 }
 async function setProfileMetadata(profileId, metafieldSlug, value, options = {}) {
-	const { ProfileCollection } = await import("./chunks/ProfileCollection-BOMOloTL.js").then((n) => n.n);
+	const { ProfileCollection } = await import("./chunks/ProfileCollection-Bix9yAiy.js").then((n) => n.r);
 	const profile = await (await ProfileCollection.create(options)).get({ id: profileId });
 	if (!profile) throw new Error(`Profile '${profileId}' not found`);
 	await profile.addMetadata(metafieldSlug, value);
 }
 async function findProfilesByMeta(metafieldSlug, value, options = {}) {
-	const { ProfileMetafieldCollection } = await import("./chunks/ProfileMetafieldCollection-C8TX9HvN.js").then((n) => n.n);
-	const { ProfileMetadataCollection } = await import("./chunks/ProfileMetadataCollection-CGcO4Iw_.js").then((n) => n.n);
+	const { ProfileMetafieldCollection } = await import("./chunks/ProfileMetafieldCollection-CACMY1hl.js").then((n) => n.n);
+	const { ProfileMetadataCollection } = await import("./chunks/ProfileMetadataCollection-loKVv_pj.js").then((n) => n.n);
 	const metafield = await (await ProfileMetafieldCollection.create(options)).getBySlug(metafieldSlug);
 	if (!metafield) throw new Error(`Metafield '${metafieldSlug}' not found`);
 	return await (await ProfileMetadataCollection.create(options)).findProfilesByMetadata(metafield.id, value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-profiles",
-  "version": "0.39.13",
+  "version": "0.39.15",
   "description": "Profile management system with relationships, metadata, and reciprocal associations for SMRT framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,6 +19,10 @@
       "types": "./dist/utils.d.ts",
       "import": "./dist/utils.js"
     },
+    "./internal/oidc-provisioning": {
+      "types": "./dist/oidc-provisioning.d.ts",
+      "import": "./dist/internal/oidc-provisioning.js"
+    },
     "./manifest": "./dist/manifest.json",
     "./manifest.json": "./dist/manifest.json"
   },
@@ -30,10 +34,10 @@
     "@happyvertical/utils": "^0.78.1",
     "@noble/curves": "^1.9.7",
     "bech32": "^2.0.0",
-    "@happyvertical/smrt-assets": "0.39.13",
-    "@happyvertical/smrt-prompts": "0.39.13",
-    "@happyvertical/smrt-tenancy": "0.39.13",
-    "@happyvertical/smrt-core": "0.39.13"
+    "@happyvertical/smrt-assets": "0.39.15",
+    "@happyvertical/smrt-tenancy": "0.39.15",
+    "@happyvertical/smrt-core": "0.39.15",
+    "@happyvertical/smrt-prompts": "0.39.15"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.5.0",
@@ -42,7 +46,7 @@
     "typescript": "^5.9.3",
     "vite": "^8.1.3",
     "vitest": "^4.1.9",
-    "@happyvertical/smrt-vitest": "0.39.13"
+    "@happyvertical/smrt-vitest": "0.39.15"
   },
   "keywords": [
     "ai",