@owlmeans/planning-auth 0.0.0-stage → 0.1.0-rc.0

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @owlmeans/planning-auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional authentication identity and group links for OwlMeans planning.
+
+```sh
+bun add @owlmeans/planning-auth@^0.1.0-rc.0
+```
+
+Register `makePlanningAuthPlugin()` for the human/non-human schemas. On a trusted server,
+`attributeCreates: true` fills missing reporters from verified creation context; an optional
+`defaultAssignee` supplies the responsible participant. Clients register the schema-only plugin.
+
+`makePlanningAuth({ planning: () => scopedFacade, provider })` exposes `assigneeFor`, `teamFor` and
+`scopeFor`. Stable provider/subject identity maps to a planning id; a nickname collision never
+retargets an existing participant. Teams carry provider-qualified external group ids. Membership
+and permission grants remain the authentication host's responsibility.
+
+Planning links always contain planning ids. Human authentication is required by the default schema;
+non-human authentication is optional. Retirement preserves historical attribution.
+
+Agent guidance ships in this package's `agent-meta` directory.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+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@^0.1.18-rc.53
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/planning-auth",
+  "version": "0.1.0-rc.0",
+  "generatedAt": "2026-10-09T11:31:12.872Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "planning-auth",
+      "category": "package-specific",
+      "file": "skills/planning-auth/SKILL.md",
+      "canonicalPath": ".agents/skills/planning-auth/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/planning-auth/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: planning-auth
+description: Optional OwlMeans authentication integration for generic planning assignees, creation attribution and external group links. Use when linking authenticated profiles or groups to planning without coupling planning contracts to an authentication provider.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/planning-auth
+
+**Install:** `"@owlmeans/planning-auth": "^0.1.0-rc.0"`. Planning itself remains provider-neutral.
+Register `makePlanningAuthPlugin()` for human/non-human assignee schemas; the default plugin is
+schema-only and safe for clients. Server hosts may set `attributeCreates: true`, `owns` and a
+`defaultAssignee` to fill missing top-level reporter/responsible fields from trusted creation context.
+
+`makePlanningAuth({ planning: () => trustedScopedFacade, provider?, humanType?, nonHumanType?,
+defaultAssignee? })` creates one context-bound adapter. `assigneeFor({ externalId, nickname,
+kind?, type?, fields? })` resolves the stable provider/subject link within the organization entity;
+it never identifies a user by display name. Nickname collisions create a distinct nickname rather
+than repointing an existing identity. Concurrent creation rereads the stable identity on conflict.
+
+`scopeFor(scope)` resolves verified profileId/userId and returns `assigneeId`, with optional
+`defaultAssigneeId`. Use only trusted authenticated scope, never caller-supplied organization ids
+or creator claims. `teamFor({ externalId, name })` resolves a provider-qualified external group
+link into a reusable planning team. It neither writes permission grants nor synchronizes group
+memberships. Hosts authorize attachment and membership through their existing access resolver.
+
+Humans require authentication unless their assignee type explicitly allows omission. Non-human
+assignees may be authenticated but do not require it. Keep all relationship references as planning
+ids; external identity ids remain integration metadata. Retirement preserves historic attribution.
+
+In viable, `makeViablePlanningAuthPlugin` owns attribution and its stable internal agent identity;
+compatibility backfill verifies old creator membership before assigning reporters. Generated targets
+use the same adapter when authenticated profile/group mapping is part of their product.
+
+## External docs
+
+- https://openid.net/specs/openid-connect-core-1_0.html#ClaimStability — issuer plus subject is stable
+  identity; names and nicknames are unsuitable as authentication keys.
+- https://www.rfc-editor.org/rfc/rfc7643.html#section-3.1 — externalId is supplied by the provisioning
+  client and scoped to the provisioning domain; retain provider context.

package/build/adapter.d.ts

@@ -0,0 +1,4 @@
+import type { PlanningAuth, PlanningAuthOptions } from './types.js';
+/** Authentication integration is an optional planning adapter; planning itself knows no user system. */
+export declare const makePlanningAuth: (opts: PlanningAuthOptions) => PlanningAuth;
+//# sourceMappingURL=adapter.d.ts.map

package/build/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAwB,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAEzF,wGAAwG;AACxG,eAAO,MAAM,gBAAgB,SAAU,mBAAmB,KAAG,YAkD5D,CAAA"}

package/build/adapter.js

@@ -0,0 +1,68 @@
+import { makePlanningAuthPlugin } from './plugin.js';
+import { AssigneeKind, FieldsInvalid, mentionHelper, WorkcardConflict } from '@owlmeans/planning';
+import { OWLMEANS_PLANNING_AUTH_PROVIDER, PLANNING_AUTH_HUMAN_TYPE, PLANNING_AUTH_NON_HUMAN_TYPE } from './consts.js';
+/** Authentication integration is an optional planning adapter; planning itself knows no user system. */
+export const makePlanningAuth = (opts) => {
+    const provider = opts.provider ?? OWLMEANS_PLANNING_AUTH_PROVIDER;
+    const humanType = opts.humanType ?? PLANNING_AUTH_HUMAN_TYPE;
+    const nonHumanType = opts.nonHumanType ?? PLANNING_AUTH_NON_HUMAN_TYPE;
+    const assigneeFor = async (identity) => {
+        if (identity.externalId.trim() === '')
+            throw new FieldsInvalid('auth:external-id-required');
+        const authentication = { provider, externalId: identity.externalId };
+        const planning = opts.planning();
+        const existing = async () => (await planning.assignees.list({ authentication, size: 1 })).items[0];
+        const found = await existing();
+        if (found != null)
+            return found;
+        const kind = identity.kind ?? AssigneeKind.Human;
+        let nickname = identity.nickname.trim();
+        if (mentionHelper.nicknameKey(nickname) === '')
+            throw new FieldsInvalid('auth:nickname-required');
+        // A nickname collision must never link an existing person to a different authentication subject.
+        if ((await planning.assignees.list({ nickname, size: 1 })).total > 0) {
+            nickname = `${nickname.slice(0, 64)}-${encodeURIComponent(identity.externalId).slice(-48)}`;
+        }
+        try {
+            return await planning.assignees.create({ nickname, kind, type: identity.type ?? (kind === AssigneeKind.Human ? humanType : nonHumanType), fields: identity.fields ?? {}, authentication });
+        }
+        catch (error) {
+            if (!(error instanceof WorkcardConflict))
+                throw error;
+            const raced = await existing();
+            if (raced == null)
+                throw error;
+            return raced;
+        }
+    };
+    const adapter = {
+        assigneeFor,
+        teamFor: async (group) => {
+            const planning = opts.planning();
+            const externalId = `${provider}:${group.externalId}`;
+            const found = (await planning.teams.list({ externalId, size: 1 })).items[0];
+            if (found != null)
+                return found;
+            try {
+                return await planning.teams.create({ name: group.name, externalId });
+            }
+            catch (error) {
+                if (!(error instanceof WorkcardConflict))
+                    throw error;
+                const raced = (await planning.teams.list({ externalId, size: 1 })).items[0];
+                if (raced == null)
+                    throw error;
+                return raced;
+            }
+        },
+        scopeFor: async (scope) => {
+            const externalId = scope.profileId ?? scope.userId ?? scope.actor?.profileId ?? scope.actor?.userId;
+            const reporter = externalId == null ? undefined : await assigneeFor({ externalId, nickname: `user-${externalId}`, kind: AssigneeKind.Human });
+            const assignee = opts.defaultAssignee == null ? undefined : await assigneeFor({ ...opts.defaultAssignee, kind: opts.defaultAssignee.kind ?? AssigneeKind.NonHuman });
+            return { ...scope, ...(reporter?.id != null ? { assigneeId: reporter.id } : {}), ...(assignee?.id != null ? { defaultAssigneeId: assignee.id } : {}) };
+        },
+        plugin: makePlanningAuthPlugin(opts),
+    };
+    return adapter;
+};
+//# sourceMappingURL=adapter.js.map

package/build/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/build/consts.d.ts

@@ -0,0 +1,4 @@
+export declare const OWLMEANS_PLANNING_AUTH_PROVIDER = "owlmeans";
+export declare const PLANNING_AUTH_HUMAN_TYPE = "planning:human";
+export declare const PLANNING_AUTH_NON_HUMAN_TYPE = "planning:automation";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,aAAa,CAAA;AACzD,eAAO,MAAM,wBAAwB,mBAAmB,CAAA;AACxD,eAAO,MAAM,4BAA4B,wBAAwB,CAAA"}

package/build/consts.js

@@ -0,0 +1,4 @@
+export const OWLMEANS_PLANNING_AUTH_PROVIDER = 'owlmeans';
+export const PLANNING_AUTH_HUMAN_TYPE = 'planning:human';
+export const PLANNING_AUTH_NON_HUMAN_TYPE = 'planning:automation';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,+BAA+B,GAAG,UAAU,CAAA;AACzD,MAAM,CAAC,MAAM,wBAAwB,GAAG,gBAAgB,CAAA;AACxD,MAAM,CAAC,MAAM,4BAA4B,GAAG,qBAAqB,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './adapter.js';
+export * from './plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAE5B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -0,0 +1,4 @@
+export * from './consts.js';
+export * from './adapter.js';
+export * from './plugin.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAE5B,cAAc,aAAa,CAAA"}

package/build/plugin.d.ts

@@ -0,0 +1,5 @@
+import { type PlanningPlugin } from '@owlmeans/planning';
+import type { PlanningAuthPluginOptions } from './types.js';
+/** Register auth identity schemas; creation attribution is an explicit server-only integration. */
+export declare const makePlanningAuthPlugin: (opts?: PlanningAuthPluginOptions) => PlanningPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/build/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,cAAc,EAAsB,MAAM,oBAAoB,CAAA;AAG5G,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAE3D,mGAAmG;AACnG,eAAO,MAAM,sBAAsB,UAAU,yBAAyB,KAAQ,cAuB5E,CAAA"}

package/build/plugin.js

@@ -0,0 +1,31 @@
+import { AssigneeKind, TransitionAction } from '@owlmeans/planning';
+import { makePlanningAuth } from './adapter.js';
+import { PLANNING_AUTH_HUMAN_TYPE, PLANNING_AUTH_NON_HUMAN_TYPE } from './consts.js';
+/** Register auth identity schemas; creation attribution is an explicit server-only integration. */
+export const makePlanningAuthPlugin = (opts = {}) => ({
+    name: opts.name ?? 'planning-auth',
+    order: opts.order ?? -100,
+    owns: opts.owns,
+    schemas: { assigneeTypes: [
+            { type: opts.humanType ?? PLANNING_AUTH_HUMAN_TYPE, version: 1, kind: AssigneeKind.Human, fields: { type: 'object', additionalProperties: true }, authentication: 'required' },
+            { type: opts.nonHumanType ?? PLANNING_AUTH_NON_HUMAN_TYPE, version: 1, kind: AssigneeKind.NonHuman, fields: { type: 'object', additionalProperties: true }, authentication: 'optional' },
+        ] },
+    ...(opts.attributeCreates === true ? {
+        before: async (exec, ctx) => {
+            if (exec.action !== TransitionAction.Create || typeof exec.card === 'string')
+                return;
+            const draft = exec.card;
+            const adapter = makePlanningAuth({ ...opts, planning: () => ctx.facade });
+            // createdBy was already stamped from the trusted actor by the executor. Trusted producers
+            // may name a known earlier creator; HTTP admission discards the caller's creator claim.
+            const reporter = draft.reporter != null || draft.createdBy == null ? undefined
+                : await adapter.assigneeFor({ externalId: draft.createdBy, nickname: `user-${draft.createdBy}` });
+            const responsible = draft.assignee != null || opts.defaultAssignee == null ? undefined
+                : await adapter.assigneeFor({ ...opts.defaultAssignee, kind: opts.defaultAssignee.kind ?? AssigneeKind.NonHuman });
+            if (reporter == null && responsible == null)
+                return;
+            return { ...exec, card: { ...draft, ...(reporter != null ? { reporter: reporter.id } : {}), ...(responsible != null ? { assignee: responsible.id } : {}) } };
+        },
+    } : {}),
+});
+//# sourceMappingURL=plugin.js.map

package/build/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -0,0 +1,33 @@
+import type { Assignee, AssigneeKind, PlanningFacade, PlanningPlugin, PlanningScope, Team } from '@owlmeans/planning';
+export interface PlanningAuthIdentity {
+    externalId: string;
+    nickname: string;
+    kind?: AssigneeKind;
+    type?: string;
+    fields?: Record<string, unknown>;
+}
+export interface PlanningAuthOptions {
+    /** Trusted, server-scoped facade; never construct from caller-supplied organization ids. */
+    planning: () => PlanningFacade;
+    provider?: string;
+    humanType?: string;
+    nonHumanType?: string;
+    defaultAssignee?: PlanningAuthIdentity;
+}
+export interface PlanningAuth {
+    assigneeFor: (identity: PlanningAuthIdentity) => Promise<Assignee>;
+    /** Resolves a planning team for a verified external group, without changing group membership. */
+    teamFor: (group: {
+        externalId: string;
+        name: string;
+    }) => Promise<Team>;
+    scopeFor: (scope: PlanningScope) => Promise<PlanningScope>;
+    plugin: PlanningPlugin;
+}
+export interface PlanningAuthPluginOptions extends Omit<PlanningAuthOptions, 'planning'> {
+    name?: string;
+    order?: number;
+    owns?: PlanningPlugin['owns'];
+    attributeCreates?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAErH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,cAAc,CAAA;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,oBAAoB,CAAA;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClE,iGAAiG;IACjG,OAAO,EAAE,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACvE,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1D,MAAM,EAAE,cAAc,CAAA;CACvB;AAED,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC;IACtF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@owlmeans/planning-auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.0",
+  "license": "MIT",
+  "description": "Optional OwlMeans authentication identity and group links for the generic planning system.",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js",
+      "default": "./build/index.js"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/planning": "^0.1.18-rc.22"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2",
+    "@owlmeans/server-planning": "^0.1.18-rc.25",
+    "@owlmeans/context": "^0.1.18-rc.34"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,58 @@
+import { makePlanningAuthPlugin } from './plugin.js'
+import { AssigneeKind, FieldsInvalid, mentionHelper, WorkcardConflict } from '@owlmeans/planning'
+import type { Assignee } from '@owlmeans/planning'
+import { OWLMEANS_PLANNING_AUTH_PROVIDER, PLANNING_AUTH_HUMAN_TYPE, PLANNING_AUTH_NON_HUMAN_TYPE } from './consts.js'
+import type { PlanningAuth, PlanningAuthIdentity, PlanningAuthOptions } from './types.js'
+
+/** Authentication integration is an optional planning adapter; planning itself knows no user system. */
+export const makePlanningAuth = (opts: PlanningAuthOptions): PlanningAuth => {
+  const provider = opts.provider ?? OWLMEANS_PLANNING_AUTH_PROVIDER
+  const humanType = opts.humanType ?? PLANNING_AUTH_HUMAN_TYPE
+  const nonHumanType = opts.nonHumanType ?? PLANNING_AUTH_NON_HUMAN_TYPE
+  const assigneeFor = async (identity: PlanningAuthIdentity): Promise<Assignee> => {
+    if (identity.externalId.trim() === '') throw new FieldsInvalid('auth:external-id-required')
+    const authentication = { provider, externalId: identity.externalId }
+    const planning = opts.planning()
+    const existing = async () => (await planning.assignees.list({ authentication, size: 1 })).items[0]
+    const found = await existing()
+    if (found != null) return found
+    const kind = identity.kind ?? AssigneeKind.Human
+    let nickname = identity.nickname.trim()
+    if (mentionHelper.nicknameKey(nickname) === '') throw new FieldsInvalid('auth:nickname-required')
+    // A nickname collision must never link an existing person to a different authentication subject.
+    if ((await planning.assignees.list({ nickname, size: 1 })).total > 0) {
+      nickname = `${nickname.slice(0, 64)}-${encodeURIComponent(identity.externalId).slice(-48)}`
+    }
+    try {
+      return await planning.assignees.create({ nickname, kind, type: identity.type ?? (kind === AssigneeKind.Human ? humanType : nonHumanType), fields: identity.fields ?? {}, authentication })
+    } catch (error) {
+      if (!(error instanceof WorkcardConflict)) throw error
+      const raced = await existing()
+      if (raced == null) throw error
+      return raced
+    }
+  }
+  const adapter: PlanningAuth = {
+    assigneeFor,
+    teamFor: async group => {
+      const planning = opts.planning()
+      const externalId = `${provider}:${group.externalId}`
+      const found = (await planning.teams.list({ externalId, size: 1 })).items[0]
+      if (found != null) return found
+      try { return await planning.teams.create({ name: group.name, externalId }) } catch (error) {
+        if (!(error instanceof WorkcardConflict)) throw error
+        const raced = (await planning.teams.list({ externalId, size: 1 })).items[0]
+        if (raced == null) throw error
+        return raced
+      }
+    },
+    scopeFor: async scope => {
+      const externalId = scope.profileId ?? scope.userId ?? scope.actor?.profileId ?? scope.actor?.userId
+      const reporter = externalId == null ? undefined : await assigneeFor({ externalId, nickname: `user-${externalId}`, kind: AssigneeKind.Human })
+      const assignee = opts.defaultAssignee == null ? undefined : await assigneeFor({ ...opts.defaultAssignee, kind: opts.defaultAssignee.kind ?? AssigneeKind.NonHuman })
+      return { ...scope, ...(reporter?.id != null ? { assigneeId: reporter.id } : {}), ...(assignee?.id != null ? { defaultAssigneeId: assignee.id } : {}) }
+    },
+    plugin: makePlanningAuthPlugin(opts),
+  }
+  return adapter
+}

package/src/consts.ts

@@ -0,0 +1,3 @@
+export const OWLMEANS_PLANNING_AUTH_PROVIDER = 'owlmeans'
+export const PLANNING_AUTH_HUMAN_TYPE = 'planning:human'
+export const PLANNING_AUTH_NON_HUMAN_TYPE = 'planning:automation'

package/src/index.ts

@@ -0,0 +1,5 @@
+export type * from './types.js'
+export * from './consts.js'
+export * from './adapter.js'
+
+export * from './plugin.js'

package/src/plugin.ts

@@ -0,0 +1,30 @@
+import { AssigneeKind, TransitionAction, type PlanningPlugin, type WorkcardDraft } from '@owlmeans/planning'
+import { makePlanningAuth } from './adapter.js'
+import { PLANNING_AUTH_HUMAN_TYPE, PLANNING_AUTH_NON_HUMAN_TYPE } from './consts.js'
+import type { PlanningAuthPluginOptions } from './types.js'
+
+/** Register auth identity schemas; creation attribution is an explicit server-only integration. */
+export const makePlanningAuthPlugin = (opts: PlanningAuthPluginOptions = {}): PlanningPlugin => ({
+  name: opts.name ?? 'planning-auth',
+  order: opts.order ?? -100,
+  owns: opts.owns,
+  schemas: { assigneeTypes: [
+    { type: opts.humanType ?? PLANNING_AUTH_HUMAN_TYPE, version: 1, kind: AssigneeKind.Human, fields: { type: 'object', additionalProperties: true }, authentication: 'required' },
+    { type: opts.nonHumanType ?? PLANNING_AUTH_NON_HUMAN_TYPE, version: 1, kind: AssigneeKind.NonHuman, fields: { type: 'object', additionalProperties: true }, authentication: 'optional' },
+  ] },
+  ...(opts.attributeCreates === true ? {
+    before: async (exec, ctx) => {
+      if (exec.action !== TransitionAction.Create || typeof exec.card === 'string') return
+      const draft = exec.card as WorkcardDraft
+      const adapter = makePlanningAuth({ ...opts, planning: () => ctx.facade })
+      // createdBy was already stamped from the trusted actor by the executor. Trusted producers
+      // may name a known earlier creator; HTTP admission discards the caller's creator claim.
+      const reporter = draft.reporter != null || draft.createdBy == null ? undefined
+        : await adapter.assigneeFor({ externalId: draft.createdBy, nickname: `user-${draft.createdBy}` })
+      const responsible = draft.assignee != null || opts.defaultAssignee == null ? undefined
+        : await adapter.assigneeFor({ ...opts.defaultAssignee, kind: opts.defaultAssignee.kind ?? AssigneeKind.NonHuman })
+      if (reporter == null && responsible == null) return
+      return { ...exec, card: { ...draft, ...(reporter != null ? { reporter: reporter.id } : {}), ...(responsible != null ? { assignee: responsible.id } : {}) } }
+    },
+  } : {}),
+})

package/src/types.ts

@@ -0,0 +1,33 @@
+import type { Assignee, AssigneeKind, PlanningFacade, PlanningPlugin, PlanningScope, Team } from '@owlmeans/planning'
+
+export interface PlanningAuthIdentity {
+  externalId: string
+  nickname: string
+  kind?: AssigneeKind
+  type?: string
+  fields?: Record<string, unknown>
+}
+
+export interface PlanningAuthOptions {
+  /** Trusted, server-scoped facade; never construct from caller-supplied organization ids. */
+  planning: () => PlanningFacade
+  provider?: string
+  humanType?: string
+  nonHumanType?: string
+  defaultAssignee?: PlanningAuthIdentity
+}
+
+export interface PlanningAuth {
+  assigneeFor: (identity: PlanningAuthIdentity) => Promise<Assignee>
+  /** Resolves a planning team for a verified external group, without changing group membership. */
+  teamFor: (group: { externalId: string, name: string }) => Promise<Team>
+  scopeFor: (scope: PlanningScope) => Promise<PlanningScope>
+  plugin: PlanningPlugin
+}
+
+export interface PlanningAuthPluginOptions extends Omit<PlanningAuthOptions, 'planning'> {
+  name?: string
+  order?: number
+  owns?: PlanningPlugin['owns']
+  attributeCreates?: boolean
+}

package/tests/adapter.spec.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType, makeBasicContext, type BasicConfig } from '@owlmeans/context'
+import { AssigneeKind, type PlanningService } from '@owlmeans/planning'
+import { appendPlanningService, makeMemoryPlanningStore } from '@owlmeans/server-planning'
+import { makePlanningAuth, makePlanningAuthPlugin } from '../src/index.js'
+
+const boot = async () => {
+  const ctx = appendPlanningService(makeBasicContext<BasicConfig>({ ready: false, service: 'auth-tests', type: AppType.Backend, services: {} }), {
+    store: makeMemoryPlanningStore(), plugins: [makePlanningAuthPlugin()],
+  })
+  await ctx.configure().init()
+  return ctx.planning() as PlanningService
+}
+describe('@owlmeans/planning-auth — optional identity integration', () => {
+  test('provider plus subject is stable across nickname and group-name changes', async () => {
+    const planning = await boot(), p = planning.for({ entityId: 'organization-1' })
+    const auth = makePlanningAuth({ planning: () => p, provider: 'external-oidc' })
+    const actor = await auth.assigneeFor({ externalId: 'subject-1', nickname: 'Alice' })
+    const again = await auth.assigneeFor({ externalId: 'subject-1', nickname: 'Changed display name' })
+    expect(again.id).toBe(actor.id)
+    expect(again.kind).toBe(AssigneeKind.Human)
+    const collision = await auth.assigneeFor({ externalId: 'subject-2', nickname: 'ALICE' })
+    expect(collision.id).not.toBe(actor.id)
+    expect(collision.nickname.toLowerCase()).not.toBe('alice')
+    const team = await auth.teamFor({ externalId: 'group-1', name: 'Editors' })
+    expect((await auth.teamFor({ externalId: 'group-1', name: 'Renamed editors' })).id).toBe(team.id)
+    expect(team.externalId).toBe('external-oidc:group-1')
+    expect(await p.teams.members(team.id!)).toEqual([])
+  })
+  test('trusted scope resolves a human reporter and a non-human default assignee per organization', async () => {
+    const planning = await boot(), p = planning.for({ entityId: 'organization-1' })
+    const adapter = makePlanningAuth({ planning: () => p, defaultAssignee: { externalId: 'agent-runner', nickname: 'agent-runner' } })
+    const scope = await adapter.scopeFor({ entityId: 'organization-1', profileId: 'app:user-1', channel: 'web' })
+    const reporter = await p.assignees.get(scope.assigneeId!), assignee = await p.assignees.get(scope.defaultAssigneeId!)
+    expect(reporter.authentication).toEqual({ provider: 'owlmeans', externalId: 'app:user-1' })
+    expect(assignee.kind).toBe(AssigneeKind.NonHuman)
+    const concurrent = await Promise.all(Array.from({ length: 5 }, () => adapter.scopeFor(scope)))
+    expect(new Set(concurrent.map(row => row.assigneeId)).size).toBe(1)
+    const other = makePlanningAuth({ planning: () => planning.for({ entityId: 'organization-2' }), defaultAssignee: { externalId: 'agent-runner', nickname: 'agent-runner' } })
+    const separate = await other.scopeFor({ entityId: 'organization-2', profileId: 'app:user-1' })
+    expect(separate.assigneeId).not.toBe(scope.assigneeId)
+    expect(separate.defaultAssigneeId).not.toBe(scope.defaultAssigneeId)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": ["@owlmeans/dep-config/tsconfig.base.json"],
+  "compilerOptions": { "rootDir": "./src/", "outDir": "./build/" },
+  "exclude": ["./build/**/*", "./tests/**/*"]
+}