@owlmeans/server-auth-identity 0.1.15 → 0.1.16

package/README.md

@@ -96,10 +96,9 @@ const { items } = await profiles.list({ entityId, profileId } as any)
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
 
-This package ships embedded Claude Code skills and GitHub Copilot instructions under
-`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
-agent-skills installer to place them into your project's native locations
-(`.claude/skills/` and `.github/instructions/`):
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
 
 ```sh
 npx @owlmeans/agent-skills

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "package": "@owlmeans/server-auth-identity",
-  "version": "0.1.15",
-  "generatedAt": "2026-08-07T17:06:32.892Z",
+  "version": "0.1.16",
+  "generatedAt": "2026-08-14T10:14:48.847Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -10,14 +10,7 @@
       "name": "server-auth-identity",
       "category": "package-specific",
       "file": "skills/server-auth-identity/SKILL.md",
-      "canonicalPath": ".claude/skills/server-auth-identity/SKILL.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "server-auth-identity",
-      "category": "package-specific",
-      "file": "instructions/server-auth-identity.instructions.md",
-      "canonicalPath": ".github/instructions/server-auth-identity.instructions.md"
+      "canonicalPath": ".agents/skills/server-auth-identity/SKILL.md"
     }
   ]
 }

package/agent-meta/skills/server-auth-identity/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/server-auth-identity
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-auth-identity": "^0.1.15"` in `dependencies`
+**Install:** `"@owlmeans/server-auth-identity": "^0.1.16"` in `dependencies`
 
 ## Key Exports
 
@@ -92,11 +92,18 @@ interface ProviderProfileDetails {
 
 ## Key Derivation Conventions
 
+- **Profile userId**: the account's mongo id — a **declared ObjectId reference**
+  (`resource.reference('userId', AUTH_IDENTITY_ACCOUNT)`): stored as `ObjectId`, exchanged
+  as a string, auto-indexed and auto-migrated at boot. The only reference in the trio.
 - **Account credential**: unique Base58 slug (16 chars) — serves as the local `entityId`
-- **Profile profileId**: `"{type}:{accountId}"` — stable across provider re-links
-- **Credentials userId** (external key): `"{type}:{service}:{providerSub}"` — uniquely identifies the external account
+- **Profile profileId**: `"{type}:{accountId}"` — stable across provider re-links; a composite key, NOT a reference
+- **Credentials userId** (external key): `"{type}:{service}:{providerSub}"` — uniquely identifies the external account. Same name as `profile.userId`, entirely different meaning — never convert or compare across the two
 - **Credentials credential** (login-service key): `"service:{type}:{service}"` — groups credentials by provider
 
+`AuthPayload.userId` is emitted as `profile.userId ?? profile.profileId`, so a value flowing
+back into a `userId` query may be a composite key — criteria tolerate it (matches nothing)
+by the reference conversion's design.
+
 ## Resource Indexes
 
 | Resource | Index | Fields | Notes |

package/build/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,uBAAuB,EAAmB,uBAAuB,EAAuB,2BAA2B,EAAE,MAAM,YAAY,CAAA;AAMtK,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,KAAG,uBAQ9D,CAAA;AAED,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,KAAG,uBAS9D,CAAA;AAED,eAAO,MAAM,+BAA+B,GAAI,UAAU,MAAM,KAAG,2BAOlE,CAAA"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,uBAAuB,EAAmB,uBAAuB,EAAuB,2BAA2B,EAAE,MAAM,YAAY,CAAA;AAMtK,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,KAAG,uBAQ9D,CAAA;AAED,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,KAAG,uBAe9D,CAAA;AAED,eAAO,MAAM,+BAA+B,GAAI,UAAU,MAAM,KAAG,2BAOlE,CAAA"}

package/build/resource.js

@@ -9,6 +9,12 @@ export const makeIdentityAccountResource = (dbAlias) => {
 };
 export const makeIdentityProfileResource = (dbAlias) => {
     const resource = makeMongoResource(AUTH_IDENTITY_PROFILE, dbAlias, undefined, undefined, AUTH_IDENTITY_PROFILE_COLLECTION);
+    /**
+     * The account's mongo id — the ONLY ObjectId reference in the identity trio.
+     * `profileId` is a composite key (`"{type}:{accountId}"`), `entityId` is the Base58
+     * slug, and `credentials.userId` is an external provider key — none of them converts.
+     */
+    resource.reference('userId', AUTH_IDENTITY_ACCOUNT);
     resource.index('userId', { userId: 1 });
     resource.index('entityId', { entityId: 1 });
     resource.index('role', { role: 1, entityId: 1 });

package/build/resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,EACL,qBAAqB,EAAE,qBAAqB,EAAE,yBAAyB,EACvE,gCAAgC,EAAE,gCAAgC,EAAE,oCAAoC,EACzG,MAAM,aAAa,CAAA;AAEpB,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,OAAgB,EAA2B,EAAE;IACvF,MAAM,QAAQ,GAAG,iBAAiB,CAChC,qBAAqB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,gCAAgC,CACvF,CAAA;IACD,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACjE,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAC3C,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACvE,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,OAAgB,EAA2B,EAAE;IACvF,MAAM,QAAQ,GAAG,iBAAiB,CAChC,qBAAqB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,gCAAgC,CACvF,CAAA;IACD,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;IACvC,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAC3C,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAChD,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1E,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,OAAgB,EAA+B,EAAE;IAC/F,MAAM,QAAQ,GAAG,iBAAiB,CAChC,yBAAyB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,oCAAoC,CAC/F,CAAA;IACD,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACnF,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAA;IAC7C,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,EACL,qBAAqB,EAAE,qBAAqB,EAAE,yBAAyB,EACvE,gCAAgC,EAAE,gCAAgC,EAAE,oCAAoC,EACzG,MAAM,aAAa,CAAA;AAEpB,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,OAAgB,EAA2B,EAAE;IACvF,MAAM,QAAQ,GAAG,iBAAiB,CAChC,qBAAqB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,gCAAgC,CACvF,CAAA;IACD,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACjE,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAC3C,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACvE,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,OAAgB,EAA2B,EAAE;IACvF,MAAM,QAAQ,GAAG,iBAAiB,CAChC,qBAAqB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,gCAAgC,CACvF,CAAA;IACD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAA;IACnD,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;IACvC,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAC3C,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAChD,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1E,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,OAAgB,EAA+B,EAAE;IAC/F,MAAM,QAAQ,GAAG,iBAAiB,CAChC,yBAAyB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,oCAAoC,CAC/F,CAAA;IACD,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACnF,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAA;IAC7C,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-auth-identity",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,13 +22,13 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.15",
-    "@owlmeans/basic-ids": "^0.1.15",
-    "@owlmeans/context": "^0.1.15",
-    "@owlmeans/mongo-resource": "^0.1.15",
-    "@owlmeans/oidc": "^0.1.15",
-    "@owlmeans/resource": "^0.1.15",
-    "@owlmeans/server-context": "^0.1.15"
+    "@owlmeans/auth": "^0.1.16",
+    "@owlmeans/basic-ids": "^0.1.16",
+    "@owlmeans/context": "^0.1.16",
+    "@owlmeans/mongo-resource": "^0.1.16",
+    "@owlmeans/oidc": "^0.1.16",
+    "@owlmeans/resource": "^0.1.16",
+    "@owlmeans/server-context": "^0.1.16"
   },
   "peerDependencies": {
     "mongodb": "*"

package/src/resource.ts

@@ -19,6 +19,12 @@ export const makeIdentityProfileResource = (dbAlias?: string): IdentityProfileRe
   const resource = makeMongoResource<IdentityProfile, IdentityProfileResource>(
     AUTH_IDENTITY_PROFILE, dbAlias, undefined, undefined, AUTH_IDENTITY_PROFILE_COLLECTION
   )
+  /**
+   * The account's mongo id — the ONLY ObjectId reference in the identity trio.
+   * `profileId` is a composite key (`"{type}:{accountId}"`), `entityId` is the Base58
+   * slug, and `credentials.userId` is an external provider key — none of them converts.
+   */
+  resource.reference('userId', AUTH_IDENTITY_ACCOUNT)
   resource.index('userId', { userId: 1 })
   resource.index('entityId', { entityId: 1 })
   resource.index('role', { role: 1, entityId: 1 })

package/agent-meta/instructions/server-auth-identity.instructions.md

@@ -1,118 +0,0 @@
----
-description: "How to use @owlmeans/server-auth-identity — Mongo-backed local identity resources (account, profile, credentials) and IdentityLinkingService for provider account linking. Use when importing appendAuthIdentityResources, makeIdentityLinkingService, or identity resource aliases."
-applyTo: "**/context.ts, **/services/**/*.ts, **/*.ts, **/*.tsx"
----
-<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
-
-# @owlmeans/server-auth-identity
-
-**Layer:** Server
-**Install:** `"@owlmeans/server-auth-identity": "^0.1.15"` in `dependencies`
-
-## Key Exports
-
-| Export | Description |
-|--------|-------------|
-| `appendAuthIdentityResources(context, dbAlias?)` | Register all three identity resources + linking service on a context |
-| `makeIdentityAccountResource(dbAlias?)` | Mongo resource for `IdentityAccount` (one per user) |
-| `makeIdentityProfileResource(dbAlias?)` | Mongo resource for `IdentityProfile` (ties user to entity + role) |
-| `makeIdentityCredentialsResource(dbAlias?)` | Mongo resource for `IdentityCredentials` (provider link per profile) |
-| `makeIdentityLinkingService()` | Service implementing `IdentityLinkingService` — links external providers to local profiles |
-| `AUTH_IDENTITY_ACCOUNT` | Resource alias `'auth-identity:account'` |
-| `AUTH_IDENTITY_PROFILE` | Resource alias `'auth-identity:profile'` |
-| `AUTH_IDENTITY_CREDENTIALS` | Resource alias `'auth-identity:credentials'` |
-| `AUTH_IDENTITY_LINKING` | Service alias `'auth-identity:linking'` |
-
-## Types
-
-| Type | Description |
-|------|-------------|
-| `IdentityAccount` | `Profile & ResourceRecord` — `id`, `credential` (unique entity slug) |
-| `IdentityProfile` | `Profile & ResourceRecord` — `id`, `profileId`, `userId?`, `role`, `entityId`, `scopes`, `expiresAt?` |
-| `IdentityCredentials` | `AuthCredentials & ResourceRecord` — `profileId`, `type`, `userId` (external key), `credential` (login-service key) |
-| `IdentityLinkingService` | `getLinkedProfile`, `linkProfile`, `linkCredentials`, `getOwnerProfiles`, `getOwnerCredentials` |
-| `IdentityAccountResource` | `MongoResource<IdentityAccount>` |
-| `IdentityProfileResource` | `MongoResource<IdentityProfile>` |
-| `IdentityCredentialsResource` | `MongoResource<IdentityCredentials>` |
-
-## Usage
-
-### Register in context
-
-```typescript
-import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
-
-// After appendMongo, appendRedis, appendAuthService:
-appendAuthIdentityResources(context)
-```
-
-### Read a profile (gate / handler)
-
-```typescript
-import { AUTH_IDENTITY_PROFILE } from '@owlmeans/server-auth-identity'
-import type { IdentityProfileResource } from '@owlmeans/server-auth-identity'
-
-const profileRes = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
-
-// Single-field indexed lookup (read-only):
-const profile = await profileRes.load(profileId, 'profileId')
-
-// Multi-field criteria lookup (read-only):
-const { items } = await profileRes.list({ entityId, profileId } as any)
-const profile = items[0] ?? null
-```
-
-### Link an external provider to a local profile
-
-```typescript
-import { AUTH_IDENTITY_LINKING } from '@owlmeans/server-auth-identity'
-import type { IdentityLinkingService } from '@owlmeans/server-auth-identity'
-
-const linking = ctx.service<IdentityLinkingService>(AUTH_IDENTITY_LINKING)
-const payload = await linking.linkProfile(providerDetails, { username })
-// Returns AuthPayload with type, role, userId, profileId, entityId, scopes
-```
-
-## Key Derivation Conventions
-
-- **Account credential**: unique Base58 slug (16 chars) — serves as the local `entityId`
-- **Profile profileId**: `"{type}:{accountId}"` — stable across provider re-links
-- **Credentials userId** (external key): `"{type}:{service}:{providerSub}"` — uniquely identifies the external account
-- **Credentials credential** (login-service key): `"service:{type}:{service}"` — groups credentials by provider
-
-## Resource Indexes
-
-| Resource | Index | Fields | Notes |
-|----------|-------|--------|-------|
-| Account | `credential` | `{ credential: 1 }` | unique |
-| Account | `entityId` | `{ entityId: 1 }` | |
-| Account | `secret` | `{ secret: 1 }` | unique, sparse |
-| Profile | `userId` | `{ userId: 1 }` | |
-| Profile | `entityId` | `{ entityId: 1 }` | |
-| Profile | `role` | `{ role: 1, entityId: 1 }` | |
-| Profile | `profile` | `{ profileId: 1, entityId: 1 }` | unique |
-| Credentials | `provider` | `{ type: 1, userId: 1, credential: 1 }` | unique |
-| Credentials | `profileId` | `{ profileId: 1 }` | |
-
-## Important Gotchas
-
-- **`Resource.pick()` is destructive** — it deletes the record. For read-only identity lookups, use `load(id, field)` for single-field indexed queries or `list(criteria)` for multi-field queries. Never use `pick()` in a gate or authorization check.
-- **`IdentityLinkingService` is compatible with `AccountLinkingService`** from `@owlmeans/server-oidc-rp` but defined independently to avoid circular dependency. Both return `AuthPayload`.
-- First-login profiles are created with `ALL_SCOPES` and `AuthRole.User` — the gate layer is initially permissive per entity.
-
-## Product-Viable Usage Notes
-
-- Register `appendAuthIdentityResources(context)` immediately after `appendAuthService(context)` so guards can authenticate before product gates authorize.
-- Product gates should load `AUTH_IDENTITY_PROFILE` read-only, verify `entityId`, reject expired/blocked profiles, then compare gate params against profile scopes.
-- Google login goes through OIDC provider config, but the durable authorization source is the local `IdentityProfile` record.
-- Account `credential` is the public local entity slug. Keep it separate from Mongo account `id` and provider subject identifiers.
-
-## Depends On
-
-- `@owlmeans/auth` — `AuthPayload`, `AuthRole`, `ALL_SCOPES`
-- `@owlmeans/basic-ids` — `createIdOfLength` for slug generation
-- `@owlmeans/context` — `appendContextual`
-- `@owlmeans/mongo-resource` — `makeMongoResource`
-- `@owlmeans/oidc` — `ProviderProfileDetails`
-- `@owlmeans/resource` — `ResourceRecord`
-- `@owlmeans/server-context` — `ServerConfig`, `ServerContext`