@owlmeans/server-auth-identity 0.1.16-rc.0 → 0.1.17

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.16-rc.0",
-  "generatedAt": "2026-08-11T14:02:34.969Z",
+  "version": "0.1.17",
+  "generatedAt": "2026-08-15T13:01:19.927Z",
   "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.16-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/server-auth-identity": "^0.1.17"` in `dependencies`
 
 ## Key Exports
 

package/build/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,eAAO,MAAM,2BAA2B,GACtC,SAAS,YAAY,CAAC,GAAG,CAAC,EAC1B,UAAU,MAAM,KACf,IAKF,CAAA"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,eAAO,MAAM,2BAA2B,YAC7B,YAAY,CAAC,GAAG,CAAC,YAChB,MAAM,KACf,IAKF,CAAA"}

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,uBAe9D,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,aAAc,MAAM,KAAG,uBAQ9D,CAAA;AAED,eAAO,MAAM,2BAA2B,aAAc,MAAM,KAAG,uBAe9D,CAAA;AAED,eAAO,MAAM,+BAA+B,aAAc,MAAM,KAAG,2BAOlE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-auth-identity",
-  "version": "0.1.16-rc.0",
+  "version": "0.1.17",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,13 +22,13 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.16-rc.0",
-    "@owlmeans/basic-ids": "^0.1.16-rc.0",
-    "@owlmeans/context": "^0.1.16-rc.0",
-    "@owlmeans/mongo-resource": "^0.1.16-rc.0",
-    "@owlmeans/oidc": "^0.1.16-rc.0",
-    "@owlmeans/resource": "^0.1.16-rc.0",
-    "@owlmeans/server-context": "^0.1.16-rc.0"
+    "@owlmeans/auth": "^0.1.17",
+    "@owlmeans/basic-ids": "^0.1.17",
+    "@owlmeans/context": "^0.1.17",
+    "@owlmeans/mongo-resource": "^0.1.17",
+    "@owlmeans/oidc": "^0.1.17",
+    "@owlmeans/resource": "^0.1.17",
+    "@owlmeans/server-context": "^0.1.17"
   },
   "peerDependencies": {
     "mongodb": "*"
@@ -37,7 +37,7 @@
     "@owlmeans/dep-config": "workspace:*",
     "@types/bun": "^1.3.14",
     "nodemon": "^3.1.14",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"

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

@@ -1,120 +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.16-rc.0"` 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
-
-- **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; a composite key, NOT a reference
-- **Credentials userId** (external key): `"{type}:{service}:{providerSub}"` — 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` = `profile.userId ?? profile.profileId` — a value flowing back into a `userId` query may be a composite key; reference criteria tolerate it (matches nothing)
-
-## 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`