@owlmeans/server-auth-identity 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +18 -1
  2. package/agent-meta/instructions/server-auth-identity.instructions.md +118 -0
  3. package/agent-meta/manifest.json +23 -0
  4. package/agent-meta/skills/server-auth-identity/SKILL.md +142 -0
  5. package/package.json +8 -8
package/README.md CHANGED
@@ -91,4 +91,21 @@ const { items } = await profiles.list({ entityId, profileId } as any)
91
91
  - [`@owlmeans/server-auth`](../server-auth) - bearer verification and default auth guard.
92
92
  - [`@owlmeans/server-oidc-rp`](../server-oidc-rp) - provider exchange and account-linking interface compatibility.
93
93
  - [`@owlmeans/oidc`](../oidc) - `ProviderProfileDetails` and provider config types.
94
- - [`@owlmeans/mongo-resource`](../mongo-resource) - Mongo-backed resource implementation.
94
+ - [`@owlmeans/mongo-resource`](../mongo-resource) - Mongo-backed resource implementation.
95
+
96
+ <!-- owlmeans:agent-guidance:start -->
97
+ ## Agent guidance
98
+
99
+ This package ships embedded Claude Code skills and GitHub Copilot instructions under
100
+ `agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
101
+ agent-skills installer to place them into your project's native locations
102
+ (`.claude/skills/` and `.github/instructions/`):
103
+
104
+ ```sh
105
+ npx @owlmeans/agent-skills
106
+ ```
107
+
108
+ The embedded files are version-matched to this package release. Do not edit them
109
+ directly — they are regenerated on each publish. To contribute guidance edits,
110
+ open a PR against the source monorepo.
111
+ <!-- owlmeans:agent-guidance:end -->
package/agent-meta/instructions/server-auth-identity.instructions.md ADDED
@@ -0,0 +1,118 @@
1
+ ---
2
+ 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."
3
+ applyTo: "**/context.ts, **/services/**/*.ts, **/*.ts, **/*.tsx"
4
+ ---
5
+ <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
6
+
7
+ # @owlmeans/server-auth-identity
8
+
9
+ **Layer:** Server
10
+ **Install:** `"@owlmeans/server-auth-identity": "^0.1.8"` in `dependencies`
11
+
12
+ ## Key Exports
13
+
14
+ | Export | Description |
15
+ |--------|-------------|
16
+ | `appendAuthIdentityResources(context, dbAlias?)` | Register all three identity resources + linking service on a context |
17
+ | `makeIdentityAccountResource(dbAlias?)` | Mongo resource for `IdentityAccount` (one per user) |
18
+ | `makeIdentityProfileResource(dbAlias?)` | Mongo resource for `IdentityProfile` (ties user to entity + role) |
19
+ | `makeIdentityCredentialsResource(dbAlias?)` | Mongo resource for `IdentityCredentials` (provider link per profile) |
20
+ | `makeIdentityLinkingService()` | Service implementing `IdentityLinkingService` — links external providers to local profiles |
21
+ | `AUTH_IDENTITY_ACCOUNT` | Resource alias `'auth-identity:account'` |
22
+ | `AUTH_IDENTITY_PROFILE` | Resource alias `'auth-identity:profile'` |
23
+ | `AUTH_IDENTITY_CREDENTIALS` | Resource alias `'auth-identity:credentials'` |
24
+ | `AUTH_IDENTITY_LINKING` | Service alias `'auth-identity:linking'` |
25
+
26
+ ## Types
27
+
28
+ | Type | Description |
29
+ |------|-------------|
30
+ | `IdentityAccount` | `Profile & ResourceRecord` — `id`, `credential` (unique entity slug) |
31
+ | `IdentityProfile` | `Profile & ResourceRecord` — `id`, `profileId`, `userId?`, `role`, `entityId`, `scopes`, `expiresAt?` |
32
+ | `IdentityCredentials` | `AuthCredentials & ResourceRecord` — `profileId`, `type`, `userId` (external key), `credential` (login-service key) |
33
+ | `IdentityLinkingService` | `getLinkedProfile`, `linkProfile`, `linkCredentials`, `getOwnerProfiles`, `getOwnerCredentials` |
34
+ | `IdentityAccountResource` | `MongoResource<IdentityAccount>` |
35
+ | `IdentityProfileResource` | `MongoResource<IdentityProfile>` |
36
+ | `IdentityCredentialsResource` | `MongoResource<IdentityCredentials>` |
37
+
38
+ ## Usage
39
+
40
+ ### Register in context
41
+
42
+ ```typescript
43
+ import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
44
+
45
+ // After appendMongo, appendRedis, appendAuthService:
46
+ appendAuthIdentityResources(context)
47
+ ```
48
+
49
+ ### Read a profile (gate / handler)
50
+
51
+ ```typescript
52
+ import { AUTH_IDENTITY_PROFILE } from '@owlmeans/server-auth-identity'
53
+ import type { IdentityProfileResource } from '@owlmeans/server-auth-identity'
54
+
55
+ const profileRes = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
56
+
57
+ // Single-field indexed lookup (read-only):
58
+ const profile = await profileRes.load(profileId, 'profileId')
59
+
60
+ // Multi-field criteria lookup (read-only):
61
+ const { items } = await profileRes.list({ entityId, profileId } as any)
62
+ const profile = items[0] ?? null
63
+ ```
64
+
65
+ ### Link an external provider to a local profile
66
+
67
+ ```typescript
68
+ import { AUTH_IDENTITY_LINKING } from '@owlmeans/server-auth-identity'
69
+ import type { IdentityLinkingService } from '@owlmeans/server-auth-identity'
70
+
71
+ const linking = ctx.service<IdentityLinkingService>(AUTH_IDENTITY_LINKING)
72
+ const payload = await linking.linkProfile(providerDetails, { username })
73
+ // Returns AuthPayload with type, role, userId, profileId, entityId, scopes
74
+ ```
75
+
76
+ ## Key Derivation Conventions
77
+
78
+ - **Account credential**: unique Base58 slug (16 chars) — serves as the local `entityId`
79
+ - **Profile profileId**: `"{type}:{accountId}"` — stable across provider re-links
80
+ - **Credentials userId** (external key): `"{type}:{service}:{providerSub}"` — uniquely identifies the external account
81
+ - **Credentials credential** (login-service key): `"service:{type}:{service}"` — groups credentials by provider
82
+
83
+ ## Resource Indexes
84
+
85
+ | Resource | Index | Fields | Notes |
86
+ |----------|-------|--------|-------|
87
+ | Account | `credential` | `{ credential: 1 }` | unique |
88
+ | Account | `entityId` | `{ entityId: 1 }` | |
89
+ | Account | `secret` | `{ secret: 1 }` | unique, sparse |
90
+ | Profile | `userId` | `{ userId: 1 }` | |
91
+ | Profile | `entityId` | `{ entityId: 1 }` | |
92
+ | Profile | `role` | `{ role: 1, entityId: 1 }` | |
93
+ | Profile | `profile` | `{ profileId: 1, entityId: 1 }` | unique |
94
+ | Credentials | `provider` | `{ type: 1, userId: 1, credential: 1 }` | unique |
95
+ | Credentials | `profileId` | `{ profileId: 1 }` | |
96
+
97
+ ## Important Gotchas
98
+
99
+ - **`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.
100
+ - **`IdentityLinkingService` is compatible with `AccountLinkingService`** from `@owlmeans/server-oidc-rp` but defined independently to avoid circular dependency. Both return `AuthPayload`.
101
+ - First-login profiles are created with `ALL_SCOPES` and `AuthRole.User` — the gate layer is initially permissive per entity.
102
+
103
+ ## Product-Viable Usage Notes
104
+
105
+ - Register `appendAuthIdentityResources(context)` immediately after `appendAuthService(context)` so guards can authenticate before product gates authorize.
106
+ - Product gates should load `AUTH_IDENTITY_PROFILE` read-only, verify `entityId`, reject expired/blocked profiles, then compare gate params against profile scopes.
107
+ - Google login goes through OIDC provider config, but the durable authorization source is the local `IdentityProfile` record.
108
+ - Account `credential` is the public local entity slug. Keep it separate from Mongo account `id` and provider subject identifiers.
109
+
110
+ ## Depends On
111
+
112
+ - `@owlmeans/auth` — `AuthPayload`, `AuthRole`, `ALL_SCOPES`
113
+ - `@owlmeans/basic-ids` — `createIdOfLength` for slug generation
114
+ - `@owlmeans/context` — `appendContextual`
115
+ - `@owlmeans/mongo-resource` — `makeMongoResource`
116
+ - `@owlmeans/oidc` — `ProviderProfileDetails`
117
+ - `@owlmeans/resource` — `ResourceRecord`
118
+ - `@owlmeans/server-context` — `ServerConfig`, `ServerContext`
package/agent-meta/manifest.json ADDED
@@ -0,0 +1,23 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "package": "@owlmeans/server-auth-identity",
4
+ "version": "0.1.8",
5
+ "generatedAt": "2026-06-11T16:30:27.162Z",
6
+ "canonicalRepo": "https://github.com/owlmeans/common",
7
+ "entries": [
8
+ {
9
+ "kind": "skill",
10
+ "name": "server-auth-identity",
11
+ "category": "package-specific",
12
+ "file": "skills/server-auth-identity/SKILL.md",
13
+ "canonicalPath": ".claude/skills/server-auth-identity/SKILL.md"
14
+ },
15
+ {
16
+ "kind": "instruction",
17
+ "name": "server-auth-identity",
18
+ "category": "package-specific",
19
+ "file": "instructions/server-auth-identity.instructions.md",
20
+ "canonicalPath": ".github/instructions/server-auth-identity.instructions.md"
21
+ }
22
+ ]
23
+ }
package/agent-meta/skills/server-auth-identity/SKILL.md ADDED
@@ -0,0 +1,142 @@
1
+ ---
2
+ name: server-auth-identity
3
+ description: How to use @owlmeans/server-auth-identity — Mongo-backed local identity resources (account, profile, credentials) and IdentityLinkingService for provider account linking. Auto-invoked when importing appendAuthIdentityResources, identity resource aliases, or IdentityLinkingService.
4
+ user-invocable: false
5
+ ---
6
+ <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
7
+
8
+ # @owlmeans/server-auth-identity
9
+
10
+ **Layer:** Server
11
+ **Install:** `"@owlmeans/server-auth-identity": "^0.1.8"` in `dependencies`
12
+
13
+ ## Key Exports
14
+
15
+ | Export | Description |
16
+ |--------|-------------|
17
+ | `appendAuthIdentityResources(context, dbAlias?)` | Register all three identity resources + linking service on a context |
18
+ | `makeIdentityAccountResource(dbAlias?)` | Mongo resource for `IdentityAccount` (one per user) |
19
+ | `makeIdentityProfileResource(dbAlias?)` | Mongo resource for `IdentityProfile` (ties user to entity + role) |
20
+ | `makeIdentityCredentialsResource(dbAlias?)` | Mongo resource for `IdentityCredentials` (provider link per profile) |
21
+ | `makeIdentityLinkingService()` | Service implementing `IdentityLinkingService` — links external providers to local profiles |
22
+ | `AUTH_IDENTITY_ACCOUNT` | Resource alias `'auth-identity:account'` |
23
+ | `AUTH_IDENTITY_PROFILE` | Resource alias `'auth-identity:profile'` |
24
+ | `AUTH_IDENTITY_CREDENTIALS` | Resource alias `'auth-identity:credentials'` |
25
+ | `AUTH_IDENTITY_LINKING` | Service alias `'auth-identity:linking'` |
26
+
27
+ ## Types
28
+
29
+ | Type | Description |
30
+ |------|-------------|
31
+ | `IdentityAccount` | `Profile & ResourceRecord` — `id`, `credential` (unique entity slug) |
32
+ | `IdentityProfile` | `Profile & ResourceRecord` — `id`, `profileId`, `userId?`, `role`, `entityId`, `scopes`, `expiresAt?` |
33
+ | `IdentityCredentials` | `AuthCredentials & ResourceRecord` — `profileId`, `type`, `userId` (external key), `credential` (login-service key) |
34
+ | `IdentityLinkingService` | `getLinkedProfile`, `linkProfile`, `linkCredentials`, `getOwnerProfiles`, `getOwnerCredentials` |
35
+
36
+ ## Usage
37
+
38
+ ### Register in context
39
+
40
+ ```typescript
41
+ import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
42
+
43
+ // In your makeContext factory, after appendMongo/appendRedis/appendAuthService:
44
+ appendAuthIdentityResources(context)
45
+ ```
46
+
47
+ This registers three Mongo resources and the linking service in one call.
48
+
49
+ ### Read a profile (gate / handler)
50
+
51
+ ```typescript
52
+ import { AUTH_IDENTITY_PROFILE } from '@owlmeans/server-auth-identity'
53
+ import type { IdentityProfileResource } from '@owlmeans/server-auth-identity'
54
+
55
+ const profileRes = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
56
+
57
+ // Single-field indexed lookup (read-only):
58
+ const profile = await profileRes.load(profileId, 'profileId')
59
+
60
+ // Multi-field criteria lookup (read-only):
61
+ const { items } = await profileRes.list({ entityId, profileId } as any)
62
+ const profile = items[0] ?? null
63
+ ```
64
+
65
+ ### Link an external provider to a local profile
66
+
67
+ ```typescript
68
+ import { AUTH_IDENTITY_LINKING } from '@owlmeans/server-auth-identity'
69
+ import type { IdentityLinkingService } from '@owlmeans/server-auth-identity'
70
+
71
+ const linking = ctx.service<IdentityLinkingService>(AUTH_IDENTITY_LINKING)
72
+
73
+ // First login — creates account + profile + credentials:
74
+ const payload = await linking.linkProfile(providerDetails, { username: 'display name' })
75
+
76
+ // Subsequent logins — finds existing profile by external key:
77
+ const payload = await linking.getLinkedProfile(providerDetails)
78
+ ```
79
+
80
+ Both return `AuthPayload` with `{ type, role, userId, profileId, entityId, scopes }`.
81
+
82
+ ### ProviderProfileDetails shape (input)
83
+
84
+ ```typescript
85
+ interface ProviderProfileDetails {
86
+ type: string // e.g. 'google'
87
+ service: string // e.g. 'google' (provider service alias)
88
+ userId: string // provider subject (sub claim)
89
+ profileId?: string // optional existing profile to link to
90
+ }
91
+ ```
92
+
93
+ ## Key Derivation Conventions
94
+
95
+ - **Account credential**: unique Base58 slug (16 chars) — serves as the local `entityId`
96
+ - **Profile profileId**: `"{type}:{accountId}"` — stable across provider re-links
97
+ - **Credentials userId** (external key): `"{type}:{service}:{providerSub}"` — uniquely identifies the external account
98
+ - **Credentials credential** (login-service key): `"service:{type}:{service}"` — groups credentials by provider
99
+
100
+ ## Resource Indexes
101
+
102
+ | Resource | Index | Fields | Notes |
103
+ |----------|-------|--------|-------|
104
+ | Account | `credential` | `{ credential: 1 }` | unique |
105
+ | Account | `entityId` | `{ entityId: 1 }` | |
106
+ | Account | `secret` | `{ secret: 1 }` | unique, sparse |
107
+ | Profile | `userId` | `{ userId: 1 }` | |
108
+ | Profile | `entityId` | `{ entityId: 1 }` | |
109
+ | Profile | `role` | `{ role: 1, entityId: 1 }` | |
110
+ | Profile | `profile` | `{ profileId: 1, entityId: 1 }` | unique |
111
+ | Credentials | `provider` | `{ type: 1, userId: 1, credential: 1 }` | unique |
112
+ | Credentials | `profileId` | `{ profileId: 1 }` | |
113
+
114
+ ## Important Gotchas
115
+
116
+ - **`Resource.pick()` is destructive** — it deletes the record it finds. For read-only identity lookups in gates or handlers, use `load(id, field)` for single-field indexed queries or `list(criteria)` for multi-field queries. Never use `pick()` in authorization checks.
117
+ - **`IdentityLinkingService` is compatible with `AccountLinkingService`** from `@owlmeans/server-oidc-rp` but defined independently to avoid circular dependency. Both return `AuthPayload`.
118
+ - First-login profiles are created with `ALL_SCOPES` and `AuthRole.User` — the gate layer is initially permissive per entity. Restrict scopes as needed for fine-grained authorization.
119
+ - Account `credential` slug generation retries up to 5 times on duplicate key collision — this is the designed behavior for the Base58 slug space.
120
+
121
+ ## Product-Viable Usage Notes
122
+
123
+ - Register `appendAuthIdentityResources(context)` immediately after `appendAuthService(context)` so guards can authenticate before product gates authorize.
124
+ - Product gates should load `AUTH_IDENTITY_PROFILE` read-only, verify `entityId`, reject expired/blocked profiles, then compare gate params against profile scopes.
125
+ - Google login goes through OIDC provider config, but the durable authorization source is the local `IdentityProfile` record.
126
+ - Account `credential` is the public local entity slug. Keep it separate from Mongo account `id` and provider subject identifiers.
127
+
128
+ ## Relationship to Other Auth Packages
129
+
130
+ - **`@owlmeans/server-auth`** — manages the auth guard (token verification). This package manages the identity store underneath.
131
+ - **`@owlmeans/server-oidc-rp`** — the OIDC relying party that can call `IdentityLinkingService` during OAuth callback to map external identity to local profile. The linking interface is compatible but independent.
132
+ - **`@owlmeans/oidc`** — provides `ProviderProfileDetails` and `OidcProviderDescriptor` types consumed by the linking service and the OIDC client.
133
+
134
+ ## Depends On
135
+
136
+ - `@owlmeans/auth` — `AuthPayload`, `AuthRole`, `ALL_SCOPES`, `Profile`, `AuthCredentials`
137
+ - `@owlmeans/basic-ids` — `createIdOfLength`, `IdStyle`
138
+ - `@owlmeans/context` — `appendContextual`
139
+ - `@owlmeans/mongo-resource` — `makeMongoResource`
140
+ - `@owlmeans/oidc` — `ProviderProfileDetails`
141
+ - `@owlmeans/resource` — `ResourceRecord`
142
+ - `@owlmeans/server-context` — `ServerConfig`, `ServerContext`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@owlmeans/server-auth-identity",
3
- "version": "0.1.7",
3
+ "version": "0.1.8",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -22,13 +22,13 @@
22
22
  }
23
23
  },
24
24
  "dependencies": {
25
- "@owlmeans/auth": "^0.1.7",
26
- "@owlmeans/basic-ids": "^0.1.7",
27
- "@owlmeans/context": "^0.1.7",
28
- "@owlmeans/mongo-resource": "^0.1.7",
29
- "@owlmeans/oidc": "^0.1.7",
30
- "@owlmeans/resource": "^0.1.7",
31
- "@owlmeans/server-context": "^0.1.7"
25
+ "@owlmeans/auth": "^0.1.8",
26
+ "@owlmeans/basic-ids": "^0.1.8",
27
+ "@owlmeans/context": "^0.1.8",
28
+ "@owlmeans/mongo-resource": "^0.1.8",
29
+ "@owlmeans/oidc": "^0.1.8",
30
+ "@owlmeans/resource": "^0.1.8",
31
+ "@owlmeans/server-context": "^0.1.8"
32
32
  },
33
33
  "peerDependencies": {
34
34
  "mongodb": "*"