@happyvertical/smrt-profiles 0.39.13 → 0.39.15

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Asset } from '@happyvertical/smrt-assets';
+import { getDatabase } from '@happyvertical/sql';
 import { PromptDefinition } from '@happyvertical/smrt-prompts';
 import { ResolvedPromptAI } from '@happyvertical/smrt-prompts';
 import { SmrtCollection } from '@happyvertical/smrt-core';
@@ -6,6 +7,13 @@ import { SmrtJunction } from '@happyvertical/smrt-core';
 import { SmrtObject } from '@happyvertical/smrt-core';
 import { SmrtObjectOptions } from '@happyvertical/smrt-core';
 
+/** More than one legacy row maps the same opaque OIDC issuer and subject. */
+export declare class AmbiguousOidcIdentityError extends Error {
+    readonly issuer: string;
+    readonly subject: string;
+    constructor(issuer: string, subject: string);
+}
+
 export declare class ApiKey extends SmrtObject {
     /**
      * Link to the Profile (Person, Organization, Bot)
@@ -272,6 +280,19 @@ export declare interface AuthContext {
     db?: SmrtObjectOptions['db'];
 }
 
+/**
+ * Populate adapter-independent Profile email keys after the schema migration.
+ *
+ * Run this from one deploy process after legacy writers are stopped or
+ * upgraded. Every read and update runs in one transaction, and repeats are a
+ * no-op.
+ */
+export declare function backfillProfileEmailKeys(db: DatabaseInterface): Promise<BackfillProfileEmailKeysResult>;
+
+export declare interface BackfillProfileEmailKeysResult {
+    updated: number;
+}
+
 /**
  * Bot profile type
  *
@@ -281,6 +302,14 @@ export declare class Bot extends Profile {
     constructor(options?: ProfileOptions);
 }
 
+/** A Profile cannot safely represent one global human identity. */
+export declare class CanonicalPersonProfileError extends Error {
+    readonly code: CanonicalPersonProfileErrorCode;
+    constructor(code: CanonicalPersonProfileErrorCode, message: string);
+}
+
+export declare type CanonicalPersonProfileErrorCode = 'ambiguous_email' | 'email_key_backfill_required' | 'email_mismatch' | 'missing_profile' | 'non_person' | 'reservation_conflict' | 'tenant_scoped';
+
 /**
  * Compute the event ID (SHA-256 hash of serialized event)
  */
@@ -355,23 +384,21 @@ export declare function createProfileFromNostr(email: string, nostrData: {
 /**
  * Create a profile from OIDC claims if it doesn't exist
  *
- * Supports email-based account linking: if a user signs in with Google
- * and later with GitHub using the same email, they get the same profile.
- *
  * Resolution order:
  * 1. If OIDC identity (iss + sub) already exists → return linked profile
- * 2. If verified email provided, check if profile with same email exists → link new identity
+ * 2. If the email matches an existing Profile, fail closed because this
+ *    package cannot prove whether a User owns it
  * 3. Otherwise, create new profile + identity
  *
  * Security considerations:
- * - Email-based linking only occurs when `email_verified` is true. This prevents
- *   attackers from claiming unverified emails to hijack accounts.
- * - Linking is automatic and irreversible through this API. Multiple OIDC
- *   identities from different providers sharing the same verified email will
- *   be associated to the same Profile.
- * - If an OIDC provider does not supply an email, or the email changes later,
- *   existing links are not automatically updated. New sign-ins without an email
- *   or with a different email may result in a new Profile being created.
+ * - Existing issuer/subject links always keep their already-linked Profile,
+ *   including legacy tenant-scoped or non-Person Profiles, and refresh the
+ *   cached identity email. This exact-link compatibility does not perform
+ *   email-based canonical reuse.
+ * - New identities never attach to an existing email match through this
+ *   Profile-only helper because Profile ownership belongs to the users package.
+ *   Use `UserCollection.getOrCreateFromOidc()` for owner-aware verified-email
+ *   reuse and its supported pre-provision resolver hook.
  * - This function trusts the OIDC provider to assert correct email_verified status.
  *   Only use with trusted providers.
  *
@@ -393,6 +420,8 @@ export declare function createProfileFromOidc(claims: {
     created: boolean;
 }>;
 
+declare type DatabaseInterface = Awaited<ReturnType<typeof getDatabase>>;
+
 /**
  * Decrypt a private key using AES-256-GCM
  * @param encrypted - Encrypted key data
@@ -676,6 +705,14 @@ export declare interface Nip05Response {
     relays?: Record<string, string[]>;
 }
 
+/**
+ * Canonicalize an email used as an external identity key.
+ *
+ * Keep this in application code: SQL `trim()` and `lower()` have
+ * adapter-specific whitespace and Unicode behavior.
+ */
+export declare function normalizeIdentityEmail(email: string): string;
+
 export declare interface NostrEvent {
     id?: string;
     pubkey: string;
@@ -883,6 +920,14 @@ export 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)
      */
@@ -900,8 +945,17 @@ export 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;
@@ -930,7 +984,11 @@ export declare class OidcIdentityCollection extends SmrtCollection<OidcIdentity>
      */
     findByProvider(provider: string): Promise<OidcIdentity[]>;
     /**
-     * Link a new OIDC identity to a profile
+     * Reuse an existing exact OIDC identity for its unchanged Profile.
+     *
+     * @deprecated New authentication links require the owner-aware,
+     * transactional provisioning APIs. This compatibility helper may refresh a
+     * legacy Profile type, but refuses to create or rebind authority.
      */
     linkToProfile(profile: Profile, oidcData: {
         provider: string;
@@ -989,12 +1047,16 @@ export 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
      *
@@ -1146,10 +1208,13 @@ export 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;
@@ -1200,6 +1265,8 @@ export declare class Profile extends SmrtObject {
     }): Promise<AuditLog>;
 }
 
+export declare const PROFILE_EMAIL_KEY_BACKFILL_NAME = "@happyvertical/smrt-profiles:profile-email-keys:v1";
+
 export declare class ProfileAsset extends SmrtObject {
     tenantId: string | null;
     profileId: string;
@@ -1230,6 +1297,7 @@ export declare interface ProfileAssetOptions extends SmrtObjectOptions {
 
 export declare class ProfileCollection extends SmrtCollection<Profile> {
     static readonly _itemClass: typeof Profile;
+    private emailKeysReadyPromise;
     /**
      * Find a profile by email address
      *
@@ -1237,6 +1305,30 @@ export declare class ProfileCollection extends SmrtCollection<Profile> {
      * @returns The matching profile or null
      */
     findByEmail(email: string): Promise<Profile | null>;
+    /**
+     * Resolve one unambiguous global Person by normalized email.
+     *
+     * Unlike `findByEmail()`, this identity-boundary helper deliberately reads
+     * across tenant scopes and fails closed when any matching row is
+     * tenant-scoped, is not a Person STI row, or when more than one row matches
+     * case-insensitively. It is intended for verified external identities.
+     */
+    findUniqueGlobalPersonByEmail(email: string): Promise<Profile | null>;
+    /**
+     * Validate and hydrate a supplied canonical Profile.
+     *
+     * The Profile must be the sole case-insensitive match for its stored email.
+     * When `email` is provided, that address must also match the stored email.
+     */
+    requireCanonicalGlobalPerson(profileId: string, email?: string): Promise<Profile>;
+    /**
+     * Reserve the normalized email for a previously validated canonical Person.
+     *
+     * The unique stored key turns a concurrent OIDC first-login race into a
+     * retryable database conflict. Legacy Profiles remain unaffected until an
+     * identity boundary safely claims them.
+     */
+    reserveCanonicalIdentityEmail(profileId: string, email?: string): Promise<Profile>;
     /**
      * Find profiles by type slug
      *
@@ -1244,6 +1336,15 @@ export declare class ProfileCollection extends SmrtCollection<Profile> {
      * @returns Array of matching profiles
      */
     findByType(typeSlug: string): Promise<Profile[]>;
+    private requireDatabase;
+    private loadCanonicalEmailRows;
+    /** Require the deploy-time backfill marker before indexed identity reads. */
+    private ensureEmailKeysReady;
+    private checkEmailKeysReady;
+    private isStaleEmailReservation;
+    private assertRowEmailKeyCurrent;
+    private assertCanonicalRows;
+    private requireHydratedProfile;
     /**
      * Batch get metadata for multiple profiles
      *
@@ -1688,6 +1789,17 @@ export declare class ProfileTypeCollection extends SmrtCollection<ProfileType> {
         name: string;
         description?: string;
     }): Promise<ProfileType>;
+    /**
+     * Atomically create or load a global ProfileType from trusted system code.
+     *
+     * This intentionally bypasses tenant auto-population and therefore refuses
+     * to run outside an explicit `withSystemContext()` boundary.
+     */
+    getOrCreateGlobalBySlug(slug: string, defaults: {
+        name: string;
+        description?: string;
+    }): Promise<ProfileType>;
+    private loadGlobalBySlug;
 }
 
 export declare interface ProfileTypeOptions extends SmrtObjectOptions {