@furystack/core 15.0.36 → 15.1.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [15.1.0] - 2026-02-19
+
+### ✨ Features
+
+### `SystemIdentityContext` -- elevated identity for trusted server-side operations
+
+Added `SystemIdentityContext`, an `IdentityContext` subclass that is always authenticated and authorized. It is intended for background jobs, migrations, and seed scripts that need to write through the `DataSet` layer without an HTTP user session.
+
+Also added the `useSystemIdentityContext()` helper that creates a scoped child injector with the elevated context. The returned injector is `AsyncDisposable` and works with `usingAsync()` for automatic cleanup.
+
+**Usage:**
+
+```typescript
+import { useSystemIdentityContext } from '@furystack/core'
+import { getDataSetFor } from '@furystack/repository'
+import { usingAsync } from '@furystack/utils'
+
+await usingAsync(useSystemIdentityContext({ injector, username: 'migration-job' }), async (systemInjector) => {
+  const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+  await dataSet.add(systemInjector, newEntity)
+})
+```
+
+### 📚 Documentation
+
+- Expanded JSDoc on `PhysicalStore` to warn that writing directly to the store bypasses DataSet authorization, hooks, and events
+
+### 🧪 Tests
+
+- Added tests for `SystemIdentityContext` (authentication, authorization, custom username)
+- Added tests for `useSystemIdentityContext` (child injector scoping, disposal, identity resolution)
+
+### ⬆️ Dependencies
+
+- Updated `@furystack/inject` and `@furystack/utils`
+
 ## [15.0.36] - 2026-02-11
 
 ### ⬆️ Dependencies

package/esm/index.d.ts

@@ -5,5 +5,6 @@ export * from './in-memory-store.js';
 export * from './store-manager.js';
 export * from './global-disposables.js';
 export * from './identity-context.js';
+export * from './system-identity-context.js';
 export * from './helpers.js';
 //# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,cAAc,CAAA"}

package/esm/index.js

@@ -5,5 +5,6 @@ export * from './in-memory-store.js';
 export * from './store-manager.js';
 export * from './global-disposables.js';
 export * from './identity-context.js';
+export * from './system-identity-context.js';
 export * from './helpers.js';
 //# sourceMappingURL=index.js.map

package/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,cAAc,CAAA"}

package/esm/models/physical-store.d.ts

@@ -62,7 +62,14 @@ export interface FindOptions<T, TSelect extends Array<keyof T>> {
 export type PartialResult<T, TFields extends Array<keyof T>> = Pick<T, TFields[number]>;
 export declare const selectFields: <T extends object, TField extends Array<keyof T>>(entry: T, ...fields: TField) => PartialResult<T, TField>;
 /**
- * Interface that defines a physical store implementation
+ * Interface that defines a physical store implementation.
+ *
+ * **Important:** Writing directly to a physical store bypasses the Repository {@link DataSet} layer.
+ * This means authorization, modification hooks, and DataSet events (used by entity sync) will **not** be triggered.
+ * For any write operation that should be observable by other parts of the system (e.g. entity sync, audit logging),
+ * use the corresponding {@link DataSet} method instead via `getDataSetFor()`.
+ *
+ * @see {@link DataSet} for the authorized, event-emitting write gateway
  */
 export interface PhysicalStore<T, TPrimaryKey extends keyof T, TWriteableData = WithOptionalId<T, TPrimaryKey>> extends EventHub<{
     onEntityAdded: {

package/esm/models/physical-store.d.ts.map

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

package/esm/system-identity-context.d.ts

@@ -0,0 +1,68 @@
+import type { Injector } from '@furystack/inject';
+import { IdentityContext } from './identity-context.js';
+import type { User } from './models/user.js';
+/**
+ * An elevated {@link IdentityContext} that is always authenticated and authorized.
+ * Intended for trusted server-side operations such as background jobs, migrations, and seed scripts.
+ *
+ * **Warning:** This context bypasses **all** authorization checks. Never use it in user-facing
+ * request pipelines or any context where untrusted input could reach the DataSet.
+ * Prefer {@link useSystemIdentityContext} for scoped usage with automatic cleanup.
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'migration-job' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, newEntity)
+ *   },
+ * )
+ * ```
+ */
+export declare class SystemIdentityContext extends IdentityContext {
+    private readonly username;
+    constructor(options?: {
+        username?: string;
+    });
+    isAuthenticated(): Promise<boolean>;
+    isAuthorized(..._roles: string[]): Promise<boolean>;
+    getCurrentUser<TUser extends User>(): Promise<TUser>;
+}
+/**
+ * Creates a scoped child injector with an elevated {@link SystemIdentityContext}.
+ * The returned injector is {@link AsyncDisposable} and works with `usingAsync()` for automatic cleanup.
+ *
+ * **Warning:** The returned injector bypasses **all** authorization checks. Only use this in trusted
+ * server-side contexts (background jobs, migrations, seed scripts). Never pass the returned injector
+ * to user-facing request handlers.
+ *
+ * @param options.injector The parent injector to create a child from
+ * @param options.username The username for the system identity (defaults to `'system'`)
+ * @returns A child injector with the SystemIdentityContext set as the IdentityContext
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'seed-script' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, { value: 'seeded' })
+ *   },
+ * )
+ * // systemInjector is disposed here -- all scoped instances cleaned up
+ * ```
+ */
+export declare const useSystemIdentityContext: (options: {
+    injector: Injector;
+    username?: string;
+}) => Injector;
+//# sourceMappingURL=system-identity-context.d.ts.map

package/esm/system-identity-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-identity-context.d.ts","sourceRoot":"","sources":["../src/system-identity-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;gBAErB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAK3B,eAAe;IAIf,YAAY,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE;IAIhC,cAAc,CAAC,KAAK,SAAS,IAAI,KAAK,OAAO,CAAC,KAAK,CAAC;CAGrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,QAK7F,CAAA"}

package/esm/system-identity-context.js

@@ -0,0 +1,75 @@
+import { IdentityContext } from './identity-context.js';
+/**
+ * An elevated {@link IdentityContext} that is always authenticated and authorized.
+ * Intended for trusted server-side operations such as background jobs, migrations, and seed scripts.
+ *
+ * **Warning:** This context bypasses **all** authorization checks. Never use it in user-facing
+ * request pipelines or any context where untrusted input could reach the DataSet.
+ * Prefer {@link useSystemIdentityContext} for scoped usage with automatic cleanup.
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'migration-job' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, newEntity)
+ *   },
+ * )
+ * ```
+ */
+export class SystemIdentityContext extends IdentityContext {
+    username;
+    constructor(options) {
+        super();
+        this.username = options?.username ?? 'system';
+    }
+    isAuthenticated() {
+        return Promise.resolve(true);
+    }
+    isAuthorized(..._roles) {
+        return Promise.resolve(true);
+    }
+    getCurrentUser() {
+        return Promise.resolve({ username: this.username, roles: [] });
+    }
+}
+/**
+ * Creates a scoped child injector with an elevated {@link SystemIdentityContext}.
+ * The returned injector is {@link AsyncDisposable} and works with `usingAsync()` for automatic cleanup.
+ *
+ * **Warning:** The returned injector bypasses **all** authorization checks. Only use this in trusted
+ * server-side contexts (background jobs, migrations, seed scripts). Never pass the returned injector
+ * to user-facing request handlers.
+ *
+ * @param options.injector The parent injector to create a child from
+ * @param options.username The username for the system identity (defaults to `'system'`)
+ * @returns A child injector with the SystemIdentityContext set as the IdentityContext
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'seed-script' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, { value: 'seeded' })
+ *   },
+ * )
+ * // systemInjector is disposed here -- all scoped instances cleaned up
+ * ```
+ */
+export const useSystemIdentityContext = (options) => {
+    const ctx = new SystemIdentityContext({ username: options.username });
+    const childInjector = options.injector.createChild({ owner: 'SystemIdentityContext' });
+    childInjector.setExplicitInstance(ctx, IdentityContext);
+    return childInjector;
+};
+//# sourceMappingURL=system-identity-context.js.map

package/esm/system-identity-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-identity-context.js","sourceRoot":"","sources":["../src/system-identity-context.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAGvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACvC,QAAQ,CAAQ;IAEjC,YAAY,OAA+B;QACzC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,QAAQ,CAAA;IAC/C,CAAC;IAEe,eAAe;QAC7B,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAEe,YAAY,CAAC,GAAG,MAAgB;QAC9C,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAEe,cAAc;QAC5B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAsB,CAAC,CAAA;IACpF,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,OAAkD,EAAY,EAAE;IACvG,MAAM,GAAG,GAAG,IAAI,qBAAqB,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IACrE,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAA;IACtF,aAAa,CAAC,mBAAmB,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;IACvD,OAAO,aAAa,CAAA;AACtB,CAAC,CAAA"}

package/esm/system-identity-context.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=system-identity-context.spec.d.ts.map

package/esm/system-identity-context.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-identity-context.spec.d.ts","sourceRoot":"","sources":["../src/system-identity-context.spec.ts"],"names":[],"mappings":""}

package/esm/system-identity-context.spec.js

@@ -0,0 +1,90 @@
+import { Injector } from '@furystack/inject';
+import { usingAsync } from '@furystack/utils';
+import { describe, expect, it } from 'vitest';
+import { getCurrentUser, isAuthenticated, isAuthorized } from './helpers.js';
+import { IdentityContext } from './identity-context.js';
+import { SystemIdentityContext, useSystemIdentityContext } from './system-identity-context.js';
+describe('SystemIdentityContext', () => {
+    it('isAuthenticated should return true', async () => {
+        const ctx = new SystemIdentityContext();
+        expect(await ctx.isAuthenticated()).toBe(true);
+    });
+    it('isAuthorized should return true without roles', async () => {
+        const ctx = new SystemIdentityContext();
+        expect(await ctx.isAuthorized()).toBe(true);
+    });
+    it('isAuthorized should return true with roles', async () => {
+        const ctx = new SystemIdentityContext();
+        expect(await ctx.isAuthorized('admin', 'superuser')).toBe(true);
+    });
+    it('getCurrentUser should return default system user', async () => {
+        const ctx = new SystemIdentityContext();
+        const user = await ctx.getCurrentUser();
+        expect(user).toEqual({ username: 'system', roles: [] });
+    });
+    it('getCurrentUser should respect custom username', async () => {
+        const ctx = new SystemIdentityContext({ username: 'migration-job' });
+        const user = await ctx.getCurrentUser();
+        expect(user).toEqual({ username: 'migration-job', roles: [] });
+    });
+});
+describe('useSystemIdentityContext', () => {
+    it('should return a child injector, not the parent', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            const child = useSystemIdentityContext({ injector: parent });
+            expect(child).not.toBe(parent);
+            await child[Symbol.asyncDispose]();
+        });
+    });
+    it('should resolve IdentityContext to a SystemIdentityContext', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+                const ctx = child.getInstance(IdentityContext);
+                expect(ctx).toBeInstanceOf(SystemIdentityContext);
+            });
+        });
+    });
+    it('should be authenticated and authorized via helpers', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+                expect(await isAuthenticated(child)).toBe(true);
+                expect(await isAuthorized(child, 'admin')).toBe(true);
+            });
+        });
+    });
+    it('should return the configured username via getCurrentUser', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent, username: 'seed-script' }), async (child) => {
+                const user = await getCurrentUser(child);
+                expect(user).toEqual({ username: 'seed-script', roles: [] });
+            });
+        });
+    });
+    it('should use default username when not specified', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+                const user = await getCurrentUser(child);
+                expect(user.username).toBe('system');
+            });
+        });
+    });
+    it('should dispose the child injector after usingAsync completes', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            let childRef;
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+                childRef = child;
+            });
+            expect(childRef).toBeDefined();
+            expect(() => childRef.getInstance(IdentityContext)).toThrow('Injector already disposed');
+        });
+    });
+    it('should not dispose the parent injector', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async () => {
+                // no-op
+            });
+            expect(() => parent.getInstance(IdentityContext)).not.toThrow();
+        });
+    });
+});
+//# sourceMappingURL=system-identity-context.spec.js.map

package/esm/system-identity-context.spec.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/core",
-  "version": "15.0.36",
+  "version": "15.1.0",
   "description": "Core FuryStack package",
   "type": "module",
   "scripts": {
@@ -46,7 +46,7 @@
   },
   "homepage": "https://github.com/furystack/furystack",
   "devDependencies": {
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.3.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },

package/src/index.ts

@@ -5,4 +5,5 @@ export * from './in-memory-store.js'
 export * from './store-manager.js'
 export * from './global-disposables.js'
 export * from './identity-context.js'
+export * from './system-identity-context.js'
 export * from './helpers.js'

package/src/models/physical-store.ts

@@ -88,7 +88,14 @@ export const selectFields = <T extends object, TField extends Array<keyof T>>(en
 }
 
 /**
- * Interface that defines a physical store implementation
+ * Interface that defines a physical store implementation.
+ *
+ * **Important:** Writing directly to a physical store bypasses the Repository {@link DataSet} layer.
+ * This means authorization, modification hooks, and DataSet events (used by entity sync) will **not** be triggered.
+ * For any write operation that should be observable by other parts of the system (e.g. entity sync, audit logging),
+ * use the corresponding {@link DataSet} method instead via `getDataSetFor()`.
+ *
+ * @see {@link DataSet} for the authorized, event-emitting write gateway
  */
 export interface PhysicalStore<
   T,

package/src/system-identity-context.spec.ts

@@ -0,0 +1,101 @@
+import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, it } from 'vitest'
+import { getCurrentUser, isAuthenticated, isAuthorized } from './helpers.js'
+import { IdentityContext } from './identity-context.js'
+import { SystemIdentityContext, useSystemIdentityContext } from './system-identity-context.js'
+
+describe('SystemIdentityContext', () => {
+  it('isAuthenticated should return true', async () => {
+    const ctx = new SystemIdentityContext()
+    expect(await ctx.isAuthenticated()).toBe(true)
+  })
+
+  it('isAuthorized should return true without roles', async () => {
+    const ctx = new SystemIdentityContext()
+    expect(await ctx.isAuthorized()).toBe(true)
+  })
+
+  it('isAuthorized should return true with roles', async () => {
+    const ctx = new SystemIdentityContext()
+    expect(await ctx.isAuthorized('admin', 'superuser')).toBe(true)
+  })
+
+  it('getCurrentUser should return default system user', async () => {
+    const ctx = new SystemIdentityContext()
+    const user = await ctx.getCurrentUser()
+    expect(user).toEqual({ username: 'system', roles: [] })
+  })
+
+  it('getCurrentUser should respect custom username', async () => {
+    const ctx = new SystemIdentityContext({ username: 'migration-job' })
+    const user = await ctx.getCurrentUser()
+    expect(user).toEqual({ username: 'migration-job', roles: [] })
+  })
+})
+
+describe('useSystemIdentityContext', () => {
+  it('should return a child injector, not the parent', async () => {
+    await usingAsync(new Injector(), async (parent) => {
+      const child = useSystemIdentityContext({ injector: parent })
+      expect(child).not.toBe(parent)
+      await child[Symbol.asyncDispose]()
+    })
+  })
+
+  it('should resolve IdentityContext to a SystemIdentityContext', async () => {
+    await usingAsync(new Injector(), async (parent) => {
+      await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+        const ctx = child.getInstance(IdentityContext)
+        expect(ctx).toBeInstanceOf(SystemIdentityContext)
+      })
+    })
+  })
+
+  it('should be authenticated and authorized via helpers', async () => {
+    await usingAsync(new Injector(), async (parent) => {
+      await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+        expect(await isAuthenticated(child)).toBe(true)
+        expect(await isAuthorized(child, 'admin')).toBe(true)
+      })
+    })
+  })
+
+  it('should return the configured username via getCurrentUser', async () => {
+    await usingAsync(new Injector(), async (parent) => {
+      await usingAsync(useSystemIdentityContext({ injector: parent, username: 'seed-script' }), async (child) => {
+        const user = await getCurrentUser(child)
+        expect(user).toEqual({ username: 'seed-script', roles: [] })
+      })
+    })
+  })
+
+  it('should use default username when not specified', async () => {
+    await usingAsync(new Injector(), async (parent) => {
+      await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+        const user = await getCurrentUser(child)
+        expect(user.username).toBe('system')
+      })
+    })
+  })
+
+  it('should dispose the child injector after usingAsync completes', async () => {
+    await usingAsync(new Injector(), async (parent) => {
+      let childRef: Injector | undefined
+      await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+        childRef = child
+      })
+      expect(childRef).toBeDefined()
+      expect(() => childRef!.getInstance(IdentityContext)).toThrow('Injector already disposed')
+    })
+  })
+
+  it('should not dispose the parent injector', async () => {
+    await usingAsync(new Injector(), async (parent) => {
+      await usingAsync(useSystemIdentityContext({ injector: parent }), async () => {
+        // no-op
+      })
+      expect(() => parent.getInstance(IdentityContext)).not.toThrow()
+    })
+  })
+})

package/src/system-identity-context.ts

@@ -0,0 +1,83 @@
+import type { Injector } from '@furystack/inject'
+
+import { IdentityContext } from './identity-context.js'
+import type { User } from './models/user.js'
+
+/**
+ * An elevated {@link IdentityContext} that is always authenticated and authorized.
+ * Intended for trusted server-side operations such as background jobs, migrations, and seed scripts.
+ *
+ * **Warning:** This context bypasses **all** authorization checks. Never use it in user-facing
+ * request pipelines or any context where untrusted input could reach the DataSet.
+ * Prefer {@link useSystemIdentityContext} for scoped usage with automatic cleanup.
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'migration-job' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, newEntity)
+ *   },
+ * )
+ * ```
+ */
+export class SystemIdentityContext extends IdentityContext {
+  private readonly username: string
+
+  constructor(options?: { username?: string }) {
+    super()
+    this.username = options?.username ?? 'system'
+  }
+
+  public override isAuthenticated() {
+    return Promise.resolve(true)
+  }
+
+  public override isAuthorized(..._roles: string[]) {
+    return Promise.resolve(true)
+  }
+
+  public override getCurrentUser<TUser extends User>(): Promise<TUser> {
+    return Promise.resolve({ username: this.username, roles: [] } as unknown as TUser)
+  }
+}
+
+/**
+ * Creates a scoped child injector with an elevated {@link SystemIdentityContext}.
+ * The returned injector is {@link AsyncDisposable} and works with `usingAsync()` for automatic cleanup.
+ *
+ * **Warning:** The returned injector bypasses **all** authorization checks. Only use this in trusted
+ * server-side contexts (background jobs, migrations, seed scripts). Never pass the returned injector
+ * to user-facing request handlers.
+ *
+ * @param options.injector The parent injector to create a child from
+ * @param options.username The username for the system identity (defaults to `'system'`)
+ * @returns A child injector with the SystemIdentityContext set as the IdentityContext
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'seed-script' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, { value: 'seeded' })
+ *   },
+ * )
+ * // systemInjector is disposed here -- all scoped instances cleaned up
+ * ```
+ */
+export const useSystemIdentityContext = (options: { injector: Injector; username?: string }): Injector => {
+  const ctx = new SystemIdentityContext({ username: options.username })
+  const childInjector = options.injector.createChild({ owner: 'SystemIdentityContext' })
+  childInjector.setExplicitInstance(ctx, IdentityContext)
+  return childInjector
+}