@astram/identity 0.13.0 → 0.15.0

package/dist/features/org-bootstrap/set-password-links.d.ts

@@ -0,0 +1,42 @@
+import { type ResetTokenStore } from '@astram/guard';
+export declare const DEFAULT_LINK_TTL_HOURS = 72;
+/** Whole hours, 1 to 168. */
+export declare function validateLinkTtlHours(hours: number): number;
+/**
+ * The reset-page base, under forgot-password's rule: outside development/test it must be set, http(s)
+ * and not loopback. Guard's resolver also checks the email-change base, which this run never uses, so
+ * that one is given a placeholder that always passes. The configured value is never echoed.
+ */
+export declare function resolveSetPasswordBase(env: NodeJS.ProcessEnv): string;
+export interface LinkTarget {
+    username: string;
+    principalId: string;
+    /** The user's company (audit tenant). */
+    tenantId: string;
+    /** Existing user whose earlier unused tokens must die first. */
+    invalidateFirst: boolean;
+    /** The stored (canonical) address; required when the links are emailed. */
+    email?: string;
+}
+/** Emails one link (G-010 `--email-links`); `true` when the provider accepted it. Never throws. */
+export type LinkDelivery = (target: LinkTarget, link: string) => Promise<boolean>;
+export interface IssueLinksInput {
+    store: ResetTokenStore;
+    targets: readonly LinkTarget[];
+    base: string;
+    ttlHours: number;
+    out: (line: string) => void;
+    /** Writes the `credential.setup_link_issued` audit row (user and expiry only). */
+    audit: (target: LinkTarget, expiresAtMs: number) => Promise<void>;
+    /** Email the links instead of printing them (G-010 R12). */
+    deliver?: LinkDelivery;
+}
+export interface IssuedLinks {
+    issued: number;
+    /** With `deliver`: links the provider accepted, and links that could not be sent (killed). */
+    emailed: number;
+    notEmailed: number;
+}
+/** Issue one token per target; print its link once, or email it with `deliver`. */
+export declare function issueSetPasswordLinks(input: IssueLinksInput): Promise<IssuedLinks>;
+//# sourceMappingURL=set-password-links.d.ts.map

package/dist/features/org-bootstrap/set-password-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-password-links.d.ts","sourceRoot":"","sources":["../../../src/features/org-bootstrap/set-password-links.ts"],"names":[],"mappings":"AAQA,OAAO,EAAsC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGzF,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAGzC,6BAA6B;AAC7B,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAarE;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,eAAe,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mGAAmG;AACnG,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAElF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,kFAAkF;IAClF,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,4DAA4D;IAC5D,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,mFAAmF;AACnF,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAoCxF"}

package/dist/features/org-bootstrap/set-password-links.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LINK_TTL_HOURS = void 0;
+exports.validateLinkTtlHours = validateLinkTtlHours;
+exports.resolveSetPasswordBase = resolveSetPasswordBase;
+exports.issueSetPasswordLinks = issueSetPasswordLinks;
+/**
+ * One-time set-password links (G-009 R8): the same token mechanism as forgot-password (32 random bytes,
+ * stored only as sha256 in the reset token store, per-row expiry), printed once to the operator's
+ * terminal, or (G-010 R12, `--email-links`) emailed through the message dispatcher instead and never
+ * printed. Links carry `&purpose=invite` (G-010 R11: wording on the reset page only; redemption
+ * ignores it). A token or link never reaches the audit row, the report or an error.
+ */
+const node_crypto_1 = require("node:crypto");
+const guard_1 = require("@astram/guard");
+const org_bootstrap_error_js_1 = require("./org-bootstrap-error.js");
+exports.DEFAULT_LINK_TTL_HOURS = 72;
+const HOUR_MS = 3_600_000;
+/** Whole hours, 1 to 168. */
+function validateLinkTtlHours(hours) {
+    if (!Number.isInteger(hours) || hours < 1 || hours > 168) {
+        throw new org_bootstrap_error_js_1.OrgBootstrapError('invalid_link_ttl', 'The link lifetime must be 1 to 168 whole hours.');
+    }
+    return hours;
+}
+/**
+ * The reset-page base, under forgot-password's rule: outside development/test it must be set, http(s)
+ * and not loopback. Guard's resolver also checks the email-change base, which this run never uses, so
+ * that one is given a placeholder that always passes. The configured value is never echoed.
+ */
+function resolveSetPasswordBase(env) {
+    try {
+        return (0, guard_1.resolveAuthLinkBaseUrls)({
+            env,
+            emailChangeLinkBaseUrlOption: 'https://email-change.not-used.example/',
+            mailDisabled: false,
+        }).resetLinkBaseUrl;
+    }
+    catch {
+        throw new org_bootstrap_error_js_1.OrgBootstrapError('link_base_url', 'RESET_LINK_BASE_URL must be set to a public http(s) URL (not localhost) outside development/test.');
+    }
+}
+/** Issue one token per target; print its link once, or email it with `deliver`. */
+async function issueSetPasswordLinks(input) {
+    let issued = 0;
+    let emailed = 0;
+    let notEmailed = 0;
+    for (const target of input.targets) {
+        if (target.invalidateFirst)
+            await input.store.invalidateAllForPrincipal(target.principalId);
+        const raw = (0, node_crypto_1.randomBytes)(32).toString('hex');
+        const expiresAtMs = Date.now() + input.ttlHours * HOUR_MS;
+        await input.store.issue(target.principalId, (0, node_crypto_1.createHash)('sha256').update(raw).digest('hex'), expiresAtMs);
+        await input.audit(target, expiresAtMs);
+        issued += 1;
+        const link = `${input.base}?token=${raw}&purpose=invite`;
+        const expires = new Date(expiresAtMs).toISOString();
+        if (input.deliver === undefined) {
+            input.out(`${target.username}  ${link}  (expires ${expires})`);
+            continue;
+        }
+        const masked = (0, guard_1.maskEmail)(target.email ?? '');
+        if (target.email !== undefined && target.email !== '' && (await input.deliver(target, link))) {
+            emailed += 1;
+            input.out(`${target.username}  set-password link emailed to ${masked}  (expires ${expires})`);
+        }
+        else {
+            // Nobody holds this link: kill it; the operator re-runs with --reissue-links.
+            await input.store.invalidateAllForPrincipal(target.principalId);
+            notEmailed += 1;
+            input.out(`${target.username}  set-password link could not be emailed to ${masked}; nothing printed. ` +
+                'Re-run with --reissue-links to send a fresh one.');
+        }
+    }
+    return { issued, emailed, notEmailed };
+}

package/dist/features/org-structure/org-catalog.service.d.ts

@@ -13,6 +13,19 @@ export declare class OrgCatalogService {
     listCompanyDepartments(companyUuid: string): Promise<NamedOption[]>;
     /** A company's branches as `{ uuid, name }` options for the posting editor. */
     listCompanyBranches(companyUuid: string): Promise<NamedOption[]>;
+    /**
+     * The id of the catalog row named `name`, creating it when none exists (G-009 R5). The catalog
+     * is global, so the lookup is by name; the create runs through the engine pipe like any write.
+     */
+    ensureDepartment(name: string): Promise<string>;
+    /** The id of the branch named `name`, creating it when none exists. */
+    ensureBranch(name: string): Promise<string>;
+    /** Link a department to a company (the junction row); idempotent. */
+    attachDepartment(companyUuid: string, departmentUuid: string): Promise<void>;
+    /** Link a branch to a company (the junction row); idempotent. */
+    attachBranch(companyUuid: string, branchUuid: string): Promise<void>;
+    private ensureCatalogRow;
+    private attachJunction;
     /** Shared reader for a company-scoped catalog junction; lists then name-resolves. */
     private listCompanyCatalog;
 }

package/dist/features/org-structure/org-catalog.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"org-catalog.service.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,qBACa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,kFAAkF;IAClF,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IASnE,+EAA+E;IAC/E,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIhE,qFAAqF;YACvE,kBAAkB;CAoBjC"}
+{"version":3,"file":"org-catalog.service.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAiB,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAQ7D,qBACa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,kFAAkF;IAClF,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IASnE,+EAA+E;IAC/E,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIhE;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C,uEAAuE;IACvE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,qEAAqE;IACrE,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E,iEAAiE;IACjE,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAItD,gBAAgB;YAOhB,cAAc;IAa5B,qFAAqF;YACvE,kBAAkB;CAoBjC"}

package/dist/features/org-structure/org-catalog.service.js

@@ -18,6 +18,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrgCatalogService = void 0;
 const common_1 = require("@nestjs/common");
 const engine_1 = require("@astram/engine");
+/** Department/branch rows have a single uuid key; a composite id here is a wiring defect. */
+function catalogId(id) {
+    if (typeof id !== 'string')
+        throw new TypeError('catalog row id is not a single uuid');
+    return id;
+}
 let OrgCatalogService = class OrgCatalogService {
     records;
     constructor(records) {
@@ -31,6 +37,40 @@ let OrgCatalogService = class OrgCatalogService {
     listCompanyBranches(companyUuid) {
         return this.listCompanyCatalog('company_branch', 'branchUuid', 'branch', companyUuid);
     }
+    /**
+     * The id of the catalog row named `name`, creating it when none exists (G-009 R5). The catalog
+     * is global, so the lookup is by name; the create runs through the engine pipe like any write.
+     */
+    ensureDepartment(name) {
+        return this.ensureCatalogRow('department', name);
+    }
+    /** The id of the branch named `name`, creating it when none exists. */
+    ensureBranch(name) {
+        return this.ensureCatalogRow('branch', name);
+    }
+    /** Link a department to a company (the junction row); idempotent. */
+    attachDepartment(companyUuid, departmentUuid) {
+        return this.attachJunction('company_department', 'departmentUuid', companyUuid, departmentUuid);
+    }
+    /** Link a branch to a company (the junction row); idempotent. */
+    attachBranch(companyUuid, branchUuid) {
+        return this.attachJunction('company_branch', 'branchUuid', companyUuid, branchUuid);
+    }
+    async ensureCatalogRow(typeKey, name) {
+        const page = await this.records.list(typeKey, { where: { name } });
+        const existing = page.rows[0];
+        if (existing !== undefined)
+            return catalogId(existing.id);
+        return catalogId(await this.records.create(typeKey, { fields: { name } }));
+    }
+    async attachJunction(junctionTypeKey, refFieldKey, companyUuid, refUuid) {
+        const page = await this.records.list(junctionTypeKey, { where: { companyUuid } });
+        if (page.rows.some((r) => r.fields[refFieldKey] === refUuid))
+            return;
+        await this.records.create(junctionTypeKey, {
+            fields: { companyUuid, [refFieldKey]: refUuid },
+        });
+    }
     /** Shared reader for a company-scoped catalog junction; lists then name-resolves. */
     async listCompanyCatalog(junctionTypeKey, refFieldKey, catalogTypeKey, companyUuid) {
         const page = await this.records.list(junctionTypeKey, { where: { companyUuid } });

package/dist/features/role/role-owner-transition.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The ONLY writer of `roles.r_owner_company_uuid` after create (G-009 T14, SPEC R13 v5). The column
+ * is immutable at the engine, so an owner change is this audited compare-and-set on the caller's
+ * connection (inside its transaction): company -> NULL (company delete) or NULL -> company (owner
+ * claim). Any other shape (company -> company, NULL -> NULL, same -> same) is refused with no write.
+ * Exactly one row must change; a stale `from` or a failing audit throws, rolling the caller back.
+ */
+import { type IdentitySchemaNames } from '../../schema.js';
+export type RoleOwnerQuery = (sql: string, params?: readonly unknown[]) => Promise<unknown>;
+/** Writes the audit row for the transition on the SAME query (connection) as the update. */
+export type RoleOwnerAudit = (action: 'role.owner_cleared' | 'role.owner_claimed', attributes: {
+    roleUuid: string;
+    from: string | null;
+    to: string | null;
+}, query: RoleOwnerQuery) => Promise<void>;
+export declare function transitionRoleOwner(query: RoleOwnerQuery, roleUuid: string, from: string | null, to: string | null, audit: RoleOwnerAudit, schemas?: IdentitySchemaNames): Promise<void>;
+//# sourceMappingURL=role-owner-transition.d.ts.map

package/dist/features/role/role-owner-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-owner-transition.d.ts","sourceRoot":"","sources":["../../../src/features/role/role-owner-transition.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEpF,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE5F,4FAA4F;AAC5F,MAAM,MAAM,cAAc,GAAG,CAC3B,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,EACnD,UAAU,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACxE,KAAK,EAAE,cAAc,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,EAAE,EAAE,MAAM,GAAG,IAAI,EACjB,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE,mBAA+C,GACvD,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/features/role/role-owner-transition.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transitionRoleOwner = transitionRoleOwner;
+/**
+ * The ONLY writer of `roles.r_owner_company_uuid` after create (G-009 T14, SPEC R13 v5). The column
+ * is immutable at the engine, so an owner change is this audited compare-and-set on the caller's
+ * connection (inside its transaction): company -> NULL (company delete) or NULL -> company (owner
+ * claim). Any other shape (company -> company, NULL -> NULL, same -> same) is refused with no write.
+ * Exactly one row must change; a stale `from` or a failing audit throws, rolling the caller back.
+ */
+const schema_js_1 = require("../../schema.js");
+async function transitionRoleOwner(query, roleUuid, from, to, audit, schemas = (0, schema_js_1.frameworkSchemasFromEnv)()) {
+    const clearing = from !== null && to === null;
+    const claiming = from === null && to !== null;
+    if (!clearing && !claiming) {
+        throw new Error('A role owner may only change from a company to none, or from none to a company.');
+    }
+    const res = (await query(`UPDATE \`${schemas.app}\`.\`roles\` SET r_owner_company_uuid = ? WHERE r_uuid = ? AND r_owner_company_uuid <=> ?`, [to, roleUuid, from]));
+    if (Number(res?.affectedRows ?? 0) !== 1) {
+        throw new Error('The role owner changed concurrently; the transition was not applied.');
+    }
+    await audit(clearing ? 'role.owner_cleared' : 'role.owner_claimed', { roleUuid, from, to }, query);
+}

package/dist/features/role/role.controller.d.ts

@@ -16,7 +16,7 @@ export declare class RoleController {
         limit: number;
     }>;
     /** Create a role — gated on `identity:role:create`. */
-    createRole(body: {
+    createRole(req: AuthedRequest, body: {
         name?: string;
     }): Promise<{
         id: import("packages/engine/dist/types.js").RecordId;

package/dist/features/role/role.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role.controller.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.controller.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOvD,qBAEa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAE/C;;;;OAIG;IAGG,SAAS,CAAU,KAAK,EAAE,YAAY;;;;;;IAM5C,uDAAuD;IAGjD,UAAU,CAAS,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAKhD;0CACsC;IAGtC,OAAO,CAA0B,IAAI,EAAE,MAAM;IAI7C,uDAAuD;IAGjD,UAAU,CACP,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EAC7B,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAMjC,uDAAuD;IAGjD,UAAU,CAAQ,GAAG,EAAE,aAAa,EAA2B,IAAI,EAAE,MAAM;;;CAIlF"}
+{"version":3,"file":"role.controller.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.controller.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOvD,qBAEa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAE/C;;;;OAIG;IAGG,SAAS,CAAU,KAAK,EAAE,YAAY;;;;;;IAM5C,uDAAuD;IAGjD,UAAU,CAAQ,GAAG,EAAE,aAAa,EAAU,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAM3E;0CACsC;IAGtC,OAAO,CAA0B,IAAI,EAAE,MAAM;IAI7C,uDAAuD;IAGjD,UAAU,CACP,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EAC7B,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAMjC,uDAAuD;IAGjD,UAAU,CAAQ,GAAG,EAAE,aAAa,EAA2B,IAAI,EAAE,MAAM;;;CAIlF"}

package/dist/features/role/role.controller.js

@@ -38,8 +38,9 @@ let RoleController = class RoleController {
         return { total: result.total, rows: result.rows, page, limit };
     }
     /** Create a role — gated on `identity:role:create`. */
-    async createRole(body) {
-        const id = await this.roles.createRole(body?.name ?? 'Untitled');
+    async createRole(req, body) {
+        // The owner is derived from the principal in the service; any owner in the body is ignored.
+        const id = await this.roles.createRole(body?.name ?? 'Untitled', req.principal);
         return { id };
     }
     /** Read one role — gated on `identity:role:read` (CONTROL-plane; root, the identity
@@ -70,9 +71,10 @@ __decorate([
 __decorate([
     (0, common_1.Post)('roles'),
     (0, guard_1.Classified)({ typeKey: 'role', action: 'create' }),
-    __param(0, (0, common_1.Body)()),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Body)()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, Object]),
     __metadata("design:returntype", Promise)
 ], RoleController.prototype, "createRole", null);
 __decorate([

package/dist/features/role/role.service.d.ts

@@ -20,8 +20,14 @@ export declare class RoleService {
     private readonly versionBump?;
     private readonly grants?;
     constructor(records: RecordsService, ceiling: GrantCeiling, versionBump?: (PostingVersionBump | null) | undefined, grants?: (GrantAdminService | null) | undefined);
-    /** Create a role. */
-    createRole(name: string): Promise<RecordId>;
+    /**
+     * Create a role. The owner is derived here from the actor, never from a client value: a non-root
+     * actor's role is owned by its active company (else its tenant); root's role is shared (no owner).
+     * A root-flagged actor bound to a declared operation (the org bootstrap's `roles` step, Shield #9)
+     * is anchored at the tenant it creates roles for, so its role is owned by that tenant.
+     * No actor (internal callers) ⇒ no owner field.
+     */
+    createRole(name: string, actor?: Principal): Promise<RecordId>;
     /** List roles (tenant-scoped by the pipe), with paging/search/sort. */
     listRoles(params?: ListParams): Promise<import("@astram/engine").RecordPage>;
     /** Read a single role. */

package/dist/features/role/role.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role.service.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAK/C;;;;;;;;;GASG;AACH,qBACa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAK7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAXP,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EAKrB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA,EAKvC,MAAM,CAAC,GAAE,iBAAiB,GAAG,IAAI,aAAA;IAGpD,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,8FAA8F;IACxF,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1F;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAoBhE"}
+{"version":3,"file":"role.service.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAe,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAK/C;;;;;;;;;GASG;AACH,qBACa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAK7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAXP,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EAKrB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA,EAKvC,MAAM,CAAC,GAAE,iBAAiB,GAAG,IAAI,aAAA;IAGpD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAQ9D,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,8FAA8F;IACxF,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1F;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAoBhE"}

package/dist/features/role/role.service.js

@@ -43,9 +43,19 @@ let RoleService = class RoleService {
         this.versionBump = versionBump;
         this.grants = grants;
     }
-    /** Create a role. */
-    createRole(name) {
-        return this.records.create('role', { fields: { name } });
+    /**
+     * Create a role. The owner is derived here from the actor, never from a client value: a non-root
+     * actor's role is owned by its active company (else its tenant); root's role is shared (no owner).
+     * A root-flagged actor bound to a declared operation (the org bootstrap's `roles` step, Shield #9)
+     * is anchored at the tenant it creates roles for, so its role is owned by that tenant.
+     * No actor (internal callers) ⇒ no owner field.
+     */
+    createRole(name, actor) {
+        const fields = { name };
+        if (actor && (actor.isRoot !== true || (0, engine_1.operationOf)(actor) !== undefined)) {
+            fields.ownerCompanyUuid = actor.activeScopeNodeId ?? actor.tenantId;
+        }
+        return this.records.create('role', { fields });
     }
     /** List roles (tenant-scoped by the pipe), with paging/search/sort. */
     listRoles(params) {

package/dist/features/user/credential-provisioner.token.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DI token for the credential provisioner `UserService.createUserWithCredential` uses (G-009 T7,
+ * OD-6): guard's `MariaDbCredentialProvisioner` (`@astram/guard/internal`), built by `IdentityFeatureModule.forRoot()` over
+ * the ONE shared authz pool. It writes the locked credential on the engine transaction's own
+ * connection, so an API-created user and its credential commit or fail together.
+ */
+export declare const IDENTITY_CREDENTIAL_PROVISIONER: unique symbol;
+//# sourceMappingURL=credential-provisioner.token.d.ts.map

package/dist/features/user/credential-provisioner.token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-provisioner.token.d.ts","sourceRoot":"","sources":["../../../src/features/user/credential-provisioner.token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,eAA4C,CAAC"}

package/dist/features/user/credential-provisioner.token.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_CREDENTIAL_PROVISIONER = void 0;
+/**
+ * DI token for the credential provisioner `UserService.createUserWithCredential` uses (G-009 T7,
+ * OD-6): guard's `MariaDbCredentialProvisioner` (`@astram/guard/internal`), built by `IdentityFeatureModule.forRoot()` over
+ * the ONE shared authz pool. It writes the locked credential on the engine transaction's own
+ * connection, so an API-created user and its credential commit or fail together.
+ */
+exports.IDENTITY_CREDENTIAL_PROVISIONER = Symbol('IDENTITY_CREDENTIAL_PROVISIONER');

package/dist/features/user/invite-message.d.ts

@@ -0,0 +1,8 @@
+/**
+ * G-010 T9 (R9, R11): the invite email. The link is HTML-escaped in the HTML part (guard's
+ * escaper is internal to guard, so a local one with the same rule plus `'`); the text part carries
+ * the plain link. Only the link and its lifetime appear: no other user data.
+ */
+import type { EmailMessage } from '@astram/core';
+export declare function inviteMessage(to: string, link: string, ttlHours: number): EmailMessage;
+//# sourceMappingURL=invite-message.d.ts.map

package/dist/features/user/invite-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite-message.d.ts","sourceRoot":"","sources":["../../../src/features/user/invite-message.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAWjD,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAWtF"}

package/dist/features/user/invite-message.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inviteMessage = inviteMessage;
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function inviteMessage(to, link, ttlHours) {
+    const lifetime = `${ttlHours} ${ttlHours === 1 ? 'hour' : 'hours'}`;
+    const intro = 'You have been invited. Set your password to sign in:';
+    const expiry = `This link works once and expires in ${lifetime}.`;
+    const safe = escapeHtml(link);
+    return {
+        to,
+        subject: 'Set your password',
+        text: `${intro} ${link}\n\n${expiry}`,
+        html: `<p>${escapeHtml(intro)} <a href="${safe}">${safe}</a></p><p>${escapeHtml(expiry)}</p>`,
+    };
+}

package/dist/features/user/invite.config.d.ts

@@ -0,0 +1,15 @@
+export interface InviteOptions {
+    /** Return the link in the invite response (once, never readable again). Default false. */
+    returnLinkToAdmin?: boolean;
+}
+export interface InviteConfig {
+    readonly returnLinkToAdmin: boolean;
+    readonly ttlHours: number;
+    readonly perAdminPerHour: number;
+    /** The reset page base, or `null` when it cannot be used (the invite answers 501). */
+    readonly linkBase: string | null;
+}
+export declare const DEFAULT_INVITE_LINK_TTL_HOURS = 72;
+export declare const DEFAULT_INVITE_RATE_PER_ADMIN = 30;
+export declare function loadInviteConfig(options?: InviteOptions, env?: NodeJS.ProcessEnv): InviteConfig;
+//# sourceMappingURL=invite.config.d.ts.map

package/dist/features/user/invite.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite.config.d.ts","sourceRoot":"","sources":["../../../src/features/user/invite.config.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAChD,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAWhD,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,aAAkB,EAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,YAAY,CAoCd"}

package/dist/features/user/invite.config.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INVITE_RATE_PER_ADMIN = exports.DEFAULT_INVITE_LINK_TTL_HOURS = void 0;
+exports.loadInviteConfig = loadInviteConfig;
+/**
+ * G-010 T9 (R11, P-4, P-5): invite configuration, read ONCE by `IdentityFeatureModule.forRoot`.
+ *
+ *  - `INVITE_LINK_TTL_HOURS`: link lifetime, whole hours 1 to 168 (default 72; the G-009 rule).
+ *  - `INVITE_RATE_PER_ADMIN`: invites one administrator may send per 60 minutes, 1 to 1000
+ *    (default 30).
+ *  - The link base follows forgot-password's `RESET_LINK_BASE_URL` rule (G-009
+ *    `resolveSetPasswordBase`). When it cannot be resolved the invite answers 501, unless the app
+ *    opted into `returnLinkToAdmin`, which then refuses boot (it promised a usable link).
+ *
+ * A bad value refuses boot with an error naming the variable, never echoing the value.
+ */
+const set_password_links_js_1 = require("../org-bootstrap/set-password-links.js");
+exports.DEFAULT_INVITE_LINK_TTL_HOURS = 72;
+exports.DEFAULT_INVITE_RATE_PER_ADMIN = 30;
+const MAX_INVITE_RATE_PER_ADMIN = 1000;
+function wholeNumber(raw, name, fallback) {
+    if (raw === undefined)
+        return fallback;
+    if (!/^\d+$/.test(raw)) {
+        throw new Error(`${name} must be a plain positive whole number.`);
+    }
+    return Number(raw);
+}
+function loadInviteConfig(options = {}, env = process.env) {
+    const ttlRaw = wholeNumber(env.INVITE_LINK_TTL_HOURS, 'INVITE_LINK_TTL_HOURS', exports.DEFAULT_INVITE_LINK_TTL_HOURS);
+    let ttlHours;
+    try {
+        ttlHours = (0, set_password_links_js_1.validateLinkTtlHours)(ttlRaw);
+    }
+    catch {
+        throw new Error('INVITE_LINK_TTL_HOURS must be 1 to 168 whole hours.');
+    }
+    const perAdminPerHour = wholeNumber(env.INVITE_RATE_PER_ADMIN, 'INVITE_RATE_PER_ADMIN', exports.DEFAULT_INVITE_RATE_PER_ADMIN);
+    if (perAdminPerHour < 1 || perAdminPerHour > MAX_INVITE_RATE_PER_ADMIN) {
+        throw new Error(`INVITE_RATE_PER_ADMIN must be 1 to ${MAX_INVITE_RATE_PER_ADMIN}.`);
+    }
+    const returnLinkToAdmin = options.returnLinkToAdmin === true;
+    let linkBase;
+    try {
+        linkBase = (0, set_password_links_js_1.resolveSetPasswordBase)(env);
+    }
+    catch (err) {
+        if (returnLinkToAdmin) {
+            throw new Error('IdentityFeatureModule.forRoot({ invite: { returnLinkToAdmin: true } }): ' +
+                (err instanceof Error ? err.message : 'RESET_LINK_BASE_URL is not usable.'));
+        }
+        linkBase = null;
+    }
+    return { returnLinkToAdmin, ttlHours, perAdminPerHour, linkBase };
+}

package/dist/features/user/invite.service.d.ts

@@ -0,0 +1,62 @@
+import { RecordsService } from '@astram/engine';
+import type { AuditEvent, Principal } from '@astram/core';
+import { type CredentialProvisioner, type MessageDispatcher, type ResetTokenStore } from '@astram/guard';
+import { GrantCeiling } from '../authz/grant-ceiling.js';
+import type { InviteConfig } from './invite.config.js';
+/**
+ * The slice of guard's `AttemptLimiter` the invite uses: `consume` is one atomic Lua step
+ * (`ATTEMPT_CONSUME_SCRIPT`: INCR, window TTL armed on the first hit and re-armed when the key has
+ * none) that answers whether this reservation is within the budget. It REJECTS when Redis cannot
+ * answer (`AttemptLimiterUnavailableError`); the invite then proceeds (fail open, P-5).
+ */
+export interface InviteLimiter {
+    consume(key: string): Promise<{
+        readonly allowed: boolean;
+        readonly count: number;
+    }>;
+}
+export interface InviteLimiters {
+    readonly user: InviteLimiter;
+    readonly admin: InviteLimiter;
+}
+export interface InviteAuditWriter {
+    record(event: AuditEvent): Promise<void>;
+}
+/** The route's response. `link` only when the app opted into `returnLinkToAdmin`. */
+export interface InviteResult {
+    emailed: boolean;
+    link?: string;
+}
+/** Invites per invited user per window (matches forgot-password's per-account limit). */
+export declare const INVITES_PER_USER = 3;
+export declare const INVITE_WINDOW_MS = 3600000;
+export declare class InviteService {
+    private readonly records;
+    private readonly ceiling;
+    private readonly config;
+    private readonly limiters?;
+    private readonly audit?;
+    private readonly resetTokens?;
+    private readonly provisioner?;
+    private readonly dispatcher?;
+    private readonly logger;
+    constructor(records: RecordsService, ceiling: GrantCeiling, config: InviteConfig, limiters?: (InviteLimiters | null) | undefined, audit?: (InviteAuditWriter | null) | undefined, resetTokens?: (ResetTokenStore | null) | undefined, provisioner?: (CredentialProvisioner | null) | undefined, dispatcher?: (MessageDispatcher | null) | undefined);
+    invite(actor: Principal, uuid: string): Promise<InviteResult>;
+    /** Only a locked credential with an email can be invited; otherwise 409 with the reason. */
+    private assertInvitable;
+    /** Reserve one slot; `false` = over the budget. A limiter that cannot answer fails open (P-5). */
+    private reserve;
+    /**
+     * Burn this invite's own token (the store's single-use consume of exactly that hash). A token a
+     * newer invite already invalidated is simply not found. A store error is logged, not thrown: the
+     * caller still answers 503 and nobody holds the link.
+     */
+    private burn;
+    private throttled;
+    /**
+     * Writes one audit row; never throws. Returns whether the row was written (`false` when no
+     * writer is wired or the sink failed), so the link-return path can fail closed on it.
+     */
+    private record;
+}
+//# sourceMappingURL=invite.service.d.ts.map

package/dist/features/user/invite.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite.service.d.ts","sourceRoot":"","sources":["../../../src/features/user/invite.service.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAOzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQvD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yFAAyF;AACzF,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,gBAAgB,UAAY,CAAC;AAW1C,qBACa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACQ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAGvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IACiB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IAGlE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAG7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAG7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAlB9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAGtC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EACW,MAAM,EAAE,YAAY,EAGpD,QAAQ,CAAC,GAAE,cAAc,GAAG,IAAI,aAAA,EACW,KAAK,CAAC,GAAE,iBAAiB,GAAG,IAAI,aAAA,EAG3E,WAAW,CAAC,GAAE,eAAe,GAAG,IAAI,aAAA,EAGpC,WAAW,CAAC,GAAE,qBAAqB,GAAG,IAAI,aAAA,EAG1C,UAAU,CAAC,GAAE,iBAAiB,GAAG,IAAI,aAAA;IAGlD,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAqGnE,4FAA4F;IAC5F,OAAO,CAAC,eAAe;IAKvB,kGAAkG;YACpF,OAAO;IASrB;;;;OAIG;YACW,IAAI;YAQJ,SAAS;IAKvB;;;OAGG;YACW,MAAM;CAuBrB"}